SDK Authentication (Partner JWT)

To ensure requests are coming from your servers, a JSON Web Token (JWT) signed by your backend is required for various operations with AIR Kit.

You need to generate and use the JWT when:

• Authenticating a User
• Performing credentials-related operations such as issuing or verifying credentials

JWT Details

• Encryptions supported: ES256, RS256
• Expiry: 5 min (recommended)
• Claims: varies depending on the operation. You would always need to include your partnerId as one of the claims
• Header: You must include a kid (Key ID) header to indicate which key was used to sign the JWT. This is important for AIR Kit to select the correct key from your JWKS endpoint for verification.
• JWKS URL - AIR Kit validates your JWT using JWK standards (https://datatracker.ietf.org/doc/html/rfc7517). By specifying your JSON Web Key Set (JWKS) endpoint, we could validate your JWT issued by your Authorization Server. - Example: https://static.air3.com/.well-known/example-jwks.json

To learn more about JWT, visit jwt.io.

Generating Partner JWTs

Generating an RS256 Key Pair

To generate a private/public key pair, you may use OpenSSL:

# Generate a 2048-bit RSA private key
openssl genpkey -algorithm RSA -out private.key -pkeyopt rsa_keygen_bits:2048

# Extract the public key in PEM format
openssl rsa -pubout -in private.key -out public.key

• private.key: Use this file as your signing key in backend code.
• public.key: Use this to configure your JWKS endpoint for JWT verification.

Tip: Keep your private key secure and never share it publicly.

Examples

Below are backend code examples for generating a JWT using ES256 or RS256 algorithms, including the kid (Key ID) header.

const jwt = require("jsonwebtoken");
const fs = require("fs");

const privateKey = fs.readFileSync("path/to/private.key");
const payload = {
  partnerId: "your-partner-id",
  // other claims as needed
  exp: Math.floor(Date.now() / 1000) + 5 * 60 // 5 minutes expiry
};

const token = jwt.sign(payload, privateKey, {
  algorithm: "RS256",
  header: {
    kid: "your-key-id"
  }
});
console.log(token);

Note: Replace "your-partner-id", "your-key-id", and private key paths with your actual values. For ES256, use the appropriate signing method and key type.