Authentication

All API requests must be authenticated using a JWT (JSON Web Token) signed with the private key we provide for your API key.

Each client is issued:

• An API key name — this identifies your integration.
• An ES256 private key — used to sign JWTs.
• One or more system values — depending on which systems your API key is authorized to act on.

Your service should generate a short-lived JWT in the Authorization header of every request:

1
Authorization: Bearer <jwt>

Requests without a valid JWT will be rejected with 401 Unauthorized.

JWT Requirements

The JWT must satisfy all of the following:

Signing Algorithm

• Must be signed using ES256

• Must be signed using the private key associated with your API key.

  The server will use the stored public key to verify signatures.

Headers

Claims

When to include sub

If your API key is associated with multiple systems, you can explicitly set:

sub: "<system>"

If your API key is associated with only one system, you should omit sub. In that case, the server will automatically assign the only system linked to your API key.

Examples

Here is a code snippet in Typescript. Alternatively, you can use our client SDK which handles signing JWT token.

1
import jwt from "jsonwebtoken"
2
3
interface GenerateJwtOptions {
4
  iss: string             // API key name
5
  sub?: string            // Optional subject
6
}
7
8
export function generateJwt(privateKey: string, { iss, sub }: GenerateJwtOptions): string {
9
  const now = Math.floor(Date.now() / 1000);
10
11
  const payload = {
12
    iss,
13
    iat: now,
14
    exp: now + 15
15
  }
16
17
  if (sub) {
18
    payload.sub = sub;
19
  }
20
21
  return jwt.sign(payload, privateKey, {
22
    algorithm: "ES256"
23
  })
24
}