> ## Documentation Index
> Fetch the complete documentation index at: https://developers.novatrade24.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Authenticate, discover your organization, and call your first endpoint in about 5 minutes.

<Warning>
  **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](https://www.novatrade24.com/contact).
</Warning>

## 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

<CodeGroup>
  ```bash cURL theme={null}
  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}"
  ```

  ```typescript TypeScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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"]
  ```

  ```java Java theme={null}
  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
  ```
</CodeGroup>

<Note>
  Tokens typically expire after 5 minutes. Cache the token and refresh before
  expiry; do not call the token endpoint on every API request.
</Note>

## 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.novatrade24.com/v1/me \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"
  ```

  ```typescript TypeScript theme={null}
  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);
  ```
</CodeGroup>

### Example response

```json theme={null}
{
  "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](/authentication), [Idempotency](/concepts/idempotency),
and [Optimistic Concurrency](/concepts/optimistic-concurrency) for details.

## 5. What next?

<CardGroup cols={2}>
  <Card title="End-to-end workflow" icon="route" href="/concepts/workflow">
    Understand how the six modules chain together into one compliance flow.
  </Card>

  <Card title="Upsert your first buyer" icon="user-plus" href="/guides/buyer-onboarding">
    Create or sync a buyer by VAT number and upload KYC documents.
  </Card>

  <Card title="Register webhooks" icon="bell" href="/webhooks/setup">
    Subscribe to compliance transitions and VIES failures.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Browse every endpoint, schema, and example.
  </Card>
</CardGroup>