Skip to content

Authentication

For API authentication we use JWT/Bearer tokens, passed on the Authorization: Bearer <token> header.

Currently supported JWT algorithms are:

  • HS256 — symmetric: the token is signed with your SECRET KEY.
  • RS256 — asymmetric: LeanX issues you a private/public key pair. You sign the token with the private key, and LeanX verifies it with the matching public key. Use this when you prefer not to sign with a shared secret.

The LeanX team will select and deliver the authentication method to be used for your integration. The algorithm is selected from the token's alg header, so the same endpoint accepts either. The required claims are identical for both; only the header and signing method differ.

JWT token header MUST include kid:

{
  "alg": "HS256",
  "typ": "JWT",
  "kid": "someuser-demo-1234567890ABCDEF"
}

Send "alg": "RS256" instead when LeanX has issued you a key pair.

For HS256 the kid is your ACCESS KEY. For RS256 the kid identifies which of the public keys issued to you by LeanX should be used to verify the signature.

JWT token body MUST include the following claims:

{
    "sub": "someuser-demo-1234567890ABCD",
    "exp": 1767225600,
    "iat": 1767225300,
    "aud": "https://api.leanx.me",
    "iss": "https://api.leanx.me"
}
  • sub — your ACCESS KEY, the same value as kid.
  • exp — expiry, UNIX timestamp in UTC. Keep tokens short-lived.
  • iat — issued-at, UNIX timestamp in UTC.
  • aud and iss — the same value in both: the base URL of the server you are calling, with no path (see Servers). Setting them to different values, or appending a path, is the usual cause of a 401.