API reference · v2

The Aleta API is located at https://api.aleta.ai/api/v2 and follows the JSON:API standard. Remember to include an access token as bearer token in your requests. See Authentication for details on how to acquire one.

Authentication with the Aleta API follows the JSON Web Token (JWT) for OAuth 2.0 standard. Requests to the API need a valid JSON Web Token (JWT) as bearer authentication.

Generate a public/private key pair

Verification of API requests is based on private/public key encryption of a JWT. For this you must first generate an ECDSA P-256 private/public key pair using a key management system (KMS). The private key will later be used for signing.

Inform Aleta about your public key

Aleta uses your public key to validate your requests for access tokens. Send your public key in JWK format to your contact at Aleta. Aleta will then assign your public key to your API user and return the values kid (key ID), iss (issuer) and sub (subject) needed for the next step.

Generate an assertion JWT

To acquire an access token that can be used to interact with the API you must provide Aleta with a signed JWT. Following the JWT standard the token consists of three parts separated by a period, <header>.<payload>.<signature>. All three elements must be base64url encoded.

The header must contain the name of the signing algorithm (ES256) and your key ID.

The payload must contain the following claims: audience (https://auth.aleta.io), issuer, subject, issued at, and expiration time. Here iat and exp are UNIX timestamps. Since the assertion JWT is only used once by the Aleta API, exp can be relatively short, i.e. 60 seconds; exp may be at most 120 seconds after iat. The audience https://api.aleta.ai/oauth/token is accepted too.

The signature is derived by joining the header and payload with a period (<header>.<payload>) and signing it with your private key. Join all three elements with a period, <header>.<payload>.<signature>, and you have your assertion token.

Acquire an access token

Call POST https://api.aleta.ai/oauth/token with the following parameters in the request body:

• grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
• assertion: the assertion JWT generated above.

The API responds with a JSON object containing three fields:

• access_token: the token that must be used for authorizing future requests.
• expires_in: number of seconds before the token expires and a new one is required (3600).
• token_type: Bearer.

The access token itself must be used as a bearer token to authenticate all your API requests. You can verify that this works by calling one of the API endpoints, e.g. GET https://api.aleta.ai/api/v2/clients, with the Authorization HTTP header set to Bearer <access token>.

A key registered on the legacy platform exchanges at https://auth.aleta.io/oauth/token, and its token works only on platform.aleta.io; api.aleta.ai answers it 401. A key Aleta registers for api.aleta.ai works on v1, v2 and v3 with the same token.

In the 2026-02-06.1 release Aleta migrated to API version v3 with a revised terminology structure, renaming asset references to instrument for asset-related endpoints:

• The Assets and Asset Classes sections are titled Instruments and Instrument Classes on v3.
• The URL path for all asset-related endpoints changed from /v2/... to /v3/....
• All relationships previously referencing asset reference instrument, for all endpoints.
• GET /performance/reporting-entities/:id expands on instruments, instrumentClasses, instrumentClassesDetailed instead of assets, assetClasses, assetClassesDetailed.
• GET /asset-holdings/reporting-entities/:id became GET /instrument-holdings/reporting-entities/:id, with the same expand change.

Other endpoints remain unchanged. The previous v2 API version remains available for backward compatibility. Custodian integration (custodians, custodian auth flows and custodian authorities) is served on v3 only.