Skip to main content
Draft specification. No production endpoint exists yet. Use the hosted mock at https://mock.api.novatrade24.com for integration design. Pilot credentials are distributed during the Santander onboarding conversation — reach out via our contact page.

​
1. Get credentials

Your Novatrade24 contact provisions an IntegrationOrganization and one or more Keycloak confidential clients. You receive:
  • client_id — e.g. api-client-santander-pilot
  • client_secret — 64+ characters, store as secret
  • Your organizationUuid and the list of authorized partnerId values (sellers you can act on behalf of)
Credentials are delivered out-of-band (secure channel). Rotate via the Keycloak admin API or by requesting a new secret.

​
2. Exchange client credentials for an access token

curl -X POST https://auth.novatrade24.com/realms/nt24-idp/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=api-client-santander-pilot" \
  -d "client_secret=${CLIENT_SECRET}"
Tokens typically expire after 5 minutes. Cache the token and refresh before expiry; do not call the token endpoint on every API request.

​
3. Discover your organization

Call GET /v1/me to learn your organization’s authorized partners and capability flags. This is the first call every client should make at startup. 
curl https://api.novatrade24.com/v1/me \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

​
Example response

{
  "organizationUuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Santander Consumer Bank",
  "authorizedPartners": [
    {
      "uuid": "11111111-2222-3333-4444-555555555555",
      "name": "AutoHandel Mustermann GmbH",
      "country": "DE"
    }
  ],
  "capabilities": {
    "rateLimitTier": "HIGH_VOLUME",
    "allowMarketplaceLedKyc": true,
    "allowMultiVinOrders": false,
    "allowContactPersonalData": true,
    "allowKycDocumentDownload": true
  },
  "dpaVersion": "2026-01",
  "dpaAcceptedAt": "2026-02-15T10:00:00Z"
}

​
4. Required headers for every request

HeaderApplies toPurpose
Authorization: Bearer <token>AllOAuth2 access token
Idempotency-Key: <uuid>All writes (POST/PATCH/DELETE)Dedupe retries
If-Match: <etag>PATCH on versioned resourcesOptimistic concurrency
X-Request-Id: <uuid>Any (optional)Your correlation ID — echoed back
X-Purpose: <code>PII-bearing endpoints (optional)Audit justification
See Authentication, Idempotency, and Optimistic Concurrency for details.

​
5. What next?

End-to-end workflow

Understand how the six modules chain together into one compliance flow.

Upsert your first buyer

Create or sync a buyer by VAT number and upload KYC documents.

Register webhooks

Subscribe to compliance transitions and VIES failures.

API Reference

Browse every endpoint, schema, and example.