Skip to main content

Authentication

To call the Jaah API from a script, a CI job or another service, use an API key. Any member creates their own under Settings › Personal › Security in the console; see API keys. A key acts as the person who created it, narrowed to the permissions ticked for it. Only an Org Owner or Org Admin can tick a key's Org administration permission, or see and revoke other members' keys.

Send the key​

Every endpoint lives under https://app.jaah.ai/api/.

Put the key's secret in the Authorization header of every request, as a bearer token:

curl https://app.jaah.ai/api/tasks \
-H "Authorization: Bearer $JAAH_API_KEY"

Every secret starts with jaah_. Keep it out of source code and logs: read it from an environment variable or the secret store of your CI system.

When a key is refused​

A refused key gets the usual error body: detail in words, and on a 403 a code naming the reason.

StatusBodyMeaning
401detail: invalid_api_keyThe secret is unknown, mistyped, expired, revoked or past its rotation overlap; or its owner is suspended, or your organization no longer admits the key.
403code: ip_not_allowedThe call came from an address outside the key's IP allowlist, or your organization's.
403code: api_key_not_allowedThe endpoint is one a key can never use (below), other than a live stream or WebSocket.
403no code (usually detail: forbidden)The key, or its owner, lacks the permission the endpoint needs.

What a key cannot reach​

Some endpoints answer only a person signed in to the console, never a key:

  • account security: passwords and email addresses (anyone's), two-factor, sessions, sign-in settings and the IP allowlist;
  • managing API keys themselves;
  • minting identities or sign-in links for other people, and resetting someone's two-factor or single sign-on;
  • personal alert channels;
  • creating or deleting an organization, and accepting the Terms of Service;
  • registering a node or issuing its token;
  • the live event stream, which answers a key with a 401 instead of a 403;
  • WebSockets, which close with code 4401.

Rotation​

Rotate a key's secret from its page in the console. You can keep the old secret working for up to 7 days while you deploy the new one; after that, calls with the old secret get invalid_api_key.