# Authentication

All API access requires machine authentication.

The platform uses certificate-based authentication combined with OAuth 2.0 token exchange.

## Machine Authentication Flow

1. Generate a JWT signed with your private key.
2. Exchange the JWT for an access token at the OAuth token endpoint.
3. Use the access token as a Bearer token in API requests.


The JWT must be signed using *RS256* and the private key associated with the registered system integration certificate.

## Required JWT Claims

| Claim | Description |
|  --- | --- |
| jti | Unique token identifier |
| iss | Certificate thumbprint |
| sub | System integration identifier |
| aud | Platform domain |
| exp | Expiration time (max 5 minutes after iat) |
| nbf | Not before time |
| iat | Issued at time |


## Token Exchange Endpoint

POST https://PLATFORM_DOMAIN/loginservice/connect/token
Content-Type: application/x-www-form-urlencoded

Request body:
grant_type=clientcertificate&client_id=clientcertificate&token=SIGNED_JWT

The response contains:

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

## Using the Access Token

Include the access token in all API requests:

Authorization: Bearer ACCESS_TOKEN

The token must be included in the Authorization header for all protected endpoints.

## Token Renewal

Access tokens are time limited.

When a token expires:

1. Generate a new signed JWT.
2. Exchange it for a new access token.
3. Retry the API request if necessary.


Integrations should cache tokens and renew them before expiration.

## User Authentication

User facing APIs use OAuth 2.0 Authorization Code Flow with PKCE.

Authorization endpoint:

https://PLATFORM_DOMAIN/loginservice/connect/authorize

This flow is used for interactive user sessions and frontend integrations.