Quickstart

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}"

const tokenResponse = await fetch(
  'https://auth.novatrade24.com/realms/nt24-idp/protocol/openid-connect/token',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: 'api-client-santander-pilot',
      client_secret: process.env.CLIENT_SECRET!,
    }),
  }
);
const { access_token, expires_in } = await tokenResponse.json();

import os, requests

r = requests.post(
    "https://auth.novatrade24.com/realms/nt24-idp/protocol/openid-connect/token",
    data={
        "grant_type": "client_credentials",
        "client_id": "api-client-santander-pilot",
        "client_secret": os.environ["CLIENT_SECRET"],
    },
)
r.raise_for_status()
access_token = r.json()["access_token"]

var body = HttpRequest.BodyPublishers.ofString(
    "grant_type=client_credentials" +
    "&client_id=api-client-santander-pilot" +
    "&client_secret=" + System.getenv("CLIENT_SECRET"));

var req = HttpRequest.newBuilder()
    .uri(URI.create("https://auth.novatrade24.com/realms/nt24-idp/protocol/openid-connect/token"))
    .header("Content-Type", "application/x-www-form-urlencoded")
    .POST(body)
    .build();

var res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
// parse JSON, extract access_token

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}"

const me = await fetch('https://api.novatrade24.com/v1/me', {
  headers: { Authorization: `Bearer ${accessToken}` },
}).then(r => r.json());

console.log(me.authorizedPartners);
console.log(me.capabilities);

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

Header	Applies to	Purpose
`Authorization: Bearer <token>`	All	OAuth2 access token
`Idempotency-Key: <uuid>`	All writes (POST/PATCH/DELETE)	Dedupe retries
`If-Match: <etag>`	PATCH on versioned resources	Optimistic 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.

Get Started

Core Concepts

Integration Guide

Webhooks

Reference

Security & Compliance

1. Get credentials

2. Exchange client credentials for an access token

3. Discover your organization

Example response

4. Required headers for every request

5. What next?

End-to-end workflow

Upsert your first buyer

Register webhooks

API Reference

​1. Get credentials

​2. Exchange client credentials for an access token

​3. Discover your organization

​Example response

​4. Required headers for every request

​5. What next?

End-to-end workflow

Upsert your first buyer

Register webhooks

API Reference

1. Get credentials

2. Exchange client credentials for an access token

3. Discover your organization

Example response

4. Required headers for every request

5. What next?