Authentication

To make requests to the AIRE API, you will need to authenticate yourself as a trusted developer or customer. Every requests to the API will be authenticated with a generated and valid JWT token.

Creating an encrypted JWT Token#

Before creating a JWT token, you will need to generate a secret key. This secret will be used to sign and encrypt the JWT token. You can create a new secret token by clicking on the "Create Secret Token" button on your dashboard.

To use this secret token, you'll need to decode it and import it with your preferred JWT library. To do this, you'll first need to decode it from base64. After you can import it using the A256GCMKW algorithm.

For more information, see the JWT specification and the available libraries for generating encrypted JWTs.

Construct a developer token as a JSON object whose header contains:

• The encryption algorithm (alg and enc) you use to encrypt the token. Use A256GCM for the enc value and direct encryption for the alg value.
• A 10-character key identifier (kid), obtained from your developer account.

In the claims payload of the token, include:

• The issuer (iss) of the token. This is the name of your developer account.
• The issued at (iat) timestamp of the token. This is the time when the token was created.
• The expiration time (exp) of the token. This is the time when the token will expire.

Make sure that the expiration time is at least 10 seconds after the issued at time, but no more than 5 minutes after the issued at time.

After creating the token, sign it with your secret key provided when you created your developer account. The secret key can be regenerated by clicking on the "Invalidate Secret Token" button on your dashboard under the "Access" panel.

Exemple:

import * as jose from 'jose' // Import the JWT library, here we use the `jose` library

// Importing the private key
const decodedJwk = JSON.parse(Buffer.from(privateKey, 'base64').toString()) // Decode privateKey from base64 to JSON
const secret = await jose.importJWK(decodedJwk, "A256GCMKW") // Import the private key

// Create a new JWT token
const jwt = await new jose.EncryptJWT({ account: "..." }) // Account is optional, pass empty object if you don't need it
        .setProtectedHeader({ alg: 'dir', enc: 'A256GCM', kid })
        .setIssuer(issuer)
        .setIssuedAt()
        .setExpirationTime("30 seconds")
        .encrypt(secret)

Authenticating Requests#

To authenticate requests to the API, you will need to pass the JWT token in the Authorization header of the request.

Make sure to include the Bearer prefix in the Authorization header.

Here's an example to test the authentication:

curl -X GET \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  https://api.aire.pr1mer.tech/test