View as Markdown

API reference · v3

The API allows you to query holding data produced by Aleta's calculation engine. Before you can access the API endpoints, you must acquire an access token used to authenticate your API requests. After stepping through the authentication guide you are ready to use the endpoints.

Base URL

The Aleta API is located at https://api.aleta.ai and follows the JSON:API standard. Remember to include an access token as bearer token in your requests.

API version v3 revised the terminology: asset references were renamed to instrument, and the URL path for all asset-related endpoints changed from /api/v2/... to /api/v3/.... All relationships previously referencing asset now reference instrument, for all endpoints. Other endpoints remain unchanged at /api/v2/... — see the v2 reference.

Base URL
https://api.aleta.ai
v3 endpoint paths
/api/v3/instruments
/api/v3/instruments/{id}
/api/v3/instruments/{reportingEntityId}/private-instruments
/api/v3/instruments/{instrumentId}/commitments
/api/v3/instruments/{instrumentId}/commitments/{commitmentId}
/api/v3/instrument-classes/{id}
/api/v3/instrument-classes-detailed/{id}

Authentication

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. v3 and v2 use the same flow and the same access tokens.

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 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. iat and exp are UNIX timestamps. Since the assertion JWT is only used once, 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 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.

Public key (JWK)
{
    "crv": "P-256",
    "kty": "EC",
    "x": "...",
    "y": "..."
}
Assertion JWT
{
    "alg": "ES256",
    "kid": "<key ID>"
}
Token exchange
POST/oauth/token
curl -X POST https://api.aleta.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  --data-urlencode "assertion={signed_jwt}"

Resource groups

For clients, users, legal entities, reporting entities, portfolios, accounts, depositories, custodian holdings, limits and webhooks, see the v2 reference.