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.
| Status | Body | Meaning |
|---|---|---|
| 401 | detail: invalid_api_key | The secret is unknown, mistyped, expired, revoked or past its rotation overlap; or its owner is suspended, or your organization no longer admits the key. |
| 403 | code: ip_not_allowed | The call came from an address outside the key's IP allowlist, or your organization's. |
| 403 | code: api_key_not_allowed | The endpoint is one a key can never use (below), other than a live stream or WebSocket. |
| 403 | no 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.