Authentication

Authentication with the Aleta API follows the JSON Web Token (JWT) for OAuth 2.0 standard. Requests to the API needs 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 the API user must (you) first generate a ECDSA P-256 private/public key pair using a key management system (KMS). The private key will later be used for signing.

warning

It is highly recommended to use a KMS that does not give any human read-access to the private key but still allows for signing. An example of this is Microsoft Azure Key Vault.

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, e.g.:

{
    "crv": "P-256",
    "kty": "EC",
    "x": "...",
    "y": "..."
}

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 encryption algorithm (ES256) and your key ID (see the previous step):

{
    "alg": "ES256",
    "kid": "<key ID>"
}

The JWT payload must contain the following claims: audience (http://auth.aleta.io), issuer, subject, issued at, and expiration time.

{ 
    "aud": "https://auth.aleta.io",
    "iss": "<issuer>", 
    "sub": "<subject>", 
    "iat": "<current time>", 
    "exp": "<exp 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.

The signature is derived by joining that 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, ready for the final step.

Acquire an Access Token

Now that you have a signed JWT, call POST https://auth.aleta.io/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 two 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 is required.

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