Authentication and authorization

Overview

This guide explains how to authenticate with the platform and describes how authorization is applied. It also includes implementation examples.

The Akkuro Lending APIs use an authorization mechanism similar to the OAuth 2.0 Client Credentials flow to ensure secure access. While it follows the core principles of machine-to-machine authentication using client credentials, there are implementation differences specific to our environment.

The access token is a JSON Web Token (JWT). Access tokens are typically short-lived and expire after a limited duration. When a token expires, request a new token using the same client credentials.

Prerequisites

• You have obtained your client credentials. Refer to How to get access to the API.

Retrieve a JWT token

Before authenticating with our APIs, use this endpoint to retrieve an access token.

Important

• Each token is issued for a specific tenant-white label pairing and cannot be used for another white label within the same tenant.

Request

Make the following request to obtain a JWT access token:

• Method: GET
• Endpoint: /authentication/token/{broker-key}/{label-reference-id}

It requires two path parameters:

Parameter	Type	Description	Required
broker-key	String	Tenant name (or broker key) used to request the token.	Yes
label-reference-id	String	White label reference ID associated with the tenant.	Yes

Provide your client credentials in the HTTP Authorization header using Basic Authentication. You can do as follows:

1. Combine your client_id and client_secret with a colon, like this: client_id:client_secret.
2. Encode the combined string using Base64.
3. Add the encoded string to the Authorization header using this format: Basic <base64-encoded-credentials>.

Request example:

If your client_id is id and your client_secret is password, the encoded string is aWQ6cGFzc3dvcmQ=.

curl --location --request GET 'https://api.eu.lending.akkuro.io/authentication/token/yourbank/yourlabel' \
--header 'Accept: application/json' \
--header 'Authorization: Basic aWQ6cGFzc3dvcmQ='

Response

A successful request returns a JWT token that you can use to authenticate subsequent API calls via the Authorization header.

When the authentication fails, you may encounter the following errors with the corresponding messages:

Code	Message	Description
400	Bad request	Incorrect API version
401	Unauthorized	Invalid client ID and secret
404	Not found	No matching broker key and label reference ID found
500	Service unavailable	Server error

Error response example:

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid client id and secret provided"
}

Validate a JWT token

There are two ways to validate your token:

• Call the validation API. See this section.
• Validate manually using the public key (JWKS). See this section.

Use validation endpoint

This endpoint validates the JWT access token included in the Authorization header. It checks whether a token is valid and not expired.

Request

Make the following request to validate a JWT token:

• Method: GET
• Endpoint: /authentication/validation
• Required HTTP headers: Authorization: Bearer {your_JWT_token}

Request example:

curl --location --request GET 'https://api.eu.lending.akkuro.io/authentication/validation' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer your_JWT_here'

Response

If the request is successful (200 OK), the token is valid and has not expired.

If the request fails, you may encounter the following errors with the corresponding messages:

Code	Message	Description
400	Bad request	Incorrect API version.
401	Service unavailable	The token is either not signed or expired.

Get public keys

Retrieve the public key from the JSON Web Key Set (JWKS) endpoint, then validate the token’s signature, expiration time, and claims on the client side. This method is useful if you want to validate tokens without making a request to our API each time.

Request

Make the following request:

• Method: GET
• Endpoint: /authentication/jwks

Request example:

curl --location --request GET 'https://api.eu.lending.akkuro.io/authentication/jwks' \
--header 'Accept: application/json'

Response

• If the request is successful (200 OK), the API returns an array of JSON Web Keys (JWKs).

Response header:

Parameter	Type	Description	Example
X-Supported-Versions	String	Lists all versions of the API currently supported by the server. Each version is separated by a comma.	2025.2.0, 2025.1.0, 2024.3.0

Response schema:

Parameter	Type	Description	Required
kty	String	The key type identifies the cryptographic algorithm family used with the key.	Yes
e	String	The public exponent of the RSA key.	Yes
use	String	Indicates the intended use of the key—such as verifying signatures or encrypting data.	No
kid	String	A unique identifier for the key.	Yes
alg	String	The algorithm intended for use with the key.	No
n	String	The modulus value of the RSA key.	Yes

A successful response example:

[
  {
    "kty": "RSA,EC",
    "e": "AQAB",
    "use": "sig",
    "kid": "2DqrwLFYncG6kxlolYO/IP6MUYU=",
    "alg": "RS256",
    "n": "i9X7Bhu_jXWv6IqPkQnLp5EXsSmdj2oF6Box6JdC36QaZkReeDwM2q0QWVf3XfiddAsFhfQ0e6K5oFrgxHoUck7gBvTfvZgLqQoA4gn0Jy7gCZEMGl6UqbuhuSWBcVL3"
  }
]

• If the request fails, you may encounter the following errors with the corresponding messages:

Code	Message	Description
400	Bad request	The request is invalid due to an apparent client error.
401	Unauthorized	The request is missing valid authentication credentials.
403	Forbidden	The request contained valid data and was understood by the server, but the server refused to act.
404	Not found	The requested resource could not be found.
500	Internal server error	The server encountered an unexpected error.

Use your JWT token in requests

Each set of client credentials is scoped to your intended use case. Therefore, your access token is limited to specific API domains (e.g., /counterparty-management) based on that scope. To access additional API domains, contact your Customer Service representative for further assistance.

When making requests, use your access token and place it into the Authorization header of the REST API request using the Bearer method.

Request example:

curl --location --request GET 'https://api.eu.lending.akkuro.io/counterparty-management/counterparties' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_JWT_HERE'

See also

After you have authenticated with our platform, you can learn more about:

• How to use our API Schemas. See Use API schema browser.
• How to specify and manage API versions. See API Versioning.