Authentication

Every request to the Korint API carries an access token identifying your client. Requests that act on a tenant’s data — nearly all of them — also carry a tenant header naming that tenant. A few endpoints are tenant-agnostic and take no tenant header; the reference shows which by not listing it under Headers.

Get your credentials

Korint provisions a machine-to-machine client for your tenant and gives you:

string

required

Public identifier for your client.

string

required

Secret for your client. Store it as you would a database password — never in frontend code or a public repository.

string

required

Your tenant identifier. It also appears in your authorization server URL.

Ask your Korint contact if you don’t have these yet. Credentials are issued per environment, so your sandbox client is not your production client.

Request an access token

Korint uses the OAuth 2.0 client credentials grant. Each tenant has its own authorization server: replace tenant in the host below with your tenant identifier.

curl -X POST 'https://korint-tenant.auth.eu-west-3.amazoncognito.com/oauth2/token' \
  --fail-with-body \
  --user '<client_id>:<client_secret>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=korint.io/policies korint.io/customers'

const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

const response = await fetch('https://korint-tenant.auth.eu-west-3.amazoncognito.com/oauth2/token', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    scope: 'korint.io/policies korint.io/customers',
  }),
});

if (!response.ok) {
  throw new Error(`Token request failed (${response.status}): ${await response.text()}`);
}

const { access_token, expires_in } = await response.json();

import requests

response = requests.post(
    "https://korint-tenant.auth.eu-west-3.amazoncognito.com/oauth2/token",
    auth=(client_id, client_secret),
    data={
        "grant_type": "client_credentials",
        "scope": "korint.io/policies korint.io/customers",
    },
)
response.raise_for_status()
access_token = response.json()["access_token"]

{
  "access_token": "eyJraWQiOiJ…",
  "token_type": "Bearer",
  "expires_in": 3600
}

Cache the token and reuse it until it expires — read expires_in rather than assuming a lifetime, and request a new token shortly before it runs out. Requesting one per API call will get you rate limited by the authorization server.

Call the API

Send the token as a bearer token and name your tenant:

curl -X GET 'https://api.korint.io/policies/{policyId}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'tenant: <your-tenant>'

The tenant header is required on every endpoint that operates on tenant data — without it the request fails with MISSING_TENANT, even when your token is valid. A few endpoints are tenant-agnostic and take no tenant header: the reference marks them by not listing it.

Scopes

Ask only for the scopes your integration needs. A token is granted the intersection of what you request and what your client is allowed.

Scope	Grants access to
`korint.io/account`	Account information for the caller
`korint.io/customers`	Customer endpoints
`korint.io/policies`	Policy endpoints
`korint.io/assets`	Asset endpoints
`korint.io/branches`	Branch endpoints
`korint.io/quotes`	Quote endpoints
`korint.io/documents`	Document endpoints
`korint.io/signature`	Signature endpoints
`korint.io/billing`	Billing endpoints
`korint.io/payments`	Payment endpoints
`korint.io/claims`	Claim endpoints
`korint.io/derogations`	Derogation endpoints
`korint.io/comments`	Comment endpoints
`korint.io/internal-notes`	Internal note endpoints
`korint.io/invitations`	Invitation and anonymous-session endpoints
`korint.io/permissions`	Permission management endpoints
`korint.io/broker`	Broker endpoints
`korint.io/reportings`	Reporting endpoints
`korint.io/analytics`	Analytics endpoints
`korint.io/external`	External lookups (vehicle, company, address)

How a request is authorized

A valid token is necessary but not sufficient. Every request passes two checks in order:

Scope check

Your token must carry the scope covering the area you are calling. Missing scope fails before any business logic runs.

Permission check

Korint then evaluates permissions on the specific record — the policy, customer or firm you named — for the identity behind the token. See Permissions.

Both must pass. A 403 therefore means one of two different things: your token lacks the scope, or your identity may not act on that particular record.

Troubleshooting

401 on every request

The token is missing, malformed, expired, or was issued by a different tenant’s authorization server than the tenant header names. Confirm the host in your token URL matches the tenant you are calling.

MISSING_TENANT

The tenant header is absent. Every endpoint that touches tenant data requires it, reads included; check the endpoint’s Headers section if you are unsure.

403 although the token is valid

Either the token lacks the scope for that area, or the identity behind it has no permission on the record you named. Compare the scopes you requested against the table above first — that is the cheaper of the two to rule out.

invalid_scope from the token endpoint

You requested a scope your client is not allowed. Request only the scopes your integration needs, or ask your Korint contact to widen the client.

​Get your credentials

​Request an access token

​Call the API

​Scopes

​How a request is authorized

​Troubleshooting

Get your credentials

Request an access token

Call the API

Scopes

How a request is authorized

Troubleshooting