Authentication

All authenticated JARAI Partner API endpoints require an API key passed via the X-API-Key HTTP header.

API Key Format

JARAI API keys carry an environment prefix so a key’s reach is obvious at a glance:

• jarai_test_{base64url} — test keys, scoped to your sandbox accounts. Keys you create yourself are always test keys.
• jarai_live_{base64url} — live keys for production access (issued once you’re approved for live mode).

Example:

jarai_test_dGhpcyBpcyBhbiBleGFtcGxlIGtleQ

The jarai_ prefix lets automated secret scanners spot a leaked key. You create API keys in the Studio Console, under Settings → API Keys, after signing in with your JARAI account. A key is shown only once, at creation — it cannot be retrieved afterwards, so store it in your secrets manager immediately. See Getting Started for the full walkthrough.

Passing Your API Key

Include the key in the X-API-Key header on every request:

curl https://api.jarai.studio/v1/partner/accounts \
-H "X-API-Key: jarai_your_api_key_here"

Scoped Keys

API keys are scoped to restrict access to specific endpoints. You choose a key’s scopes when you create it in the Studio Console — new keys default to a least-privilege, read-only set. Scopes follow a resource:action convention, and a :write scope automatically includes the matching :read.

A request to an endpoint your key isn’t scoped for returns 403 PERMISSION_DENIED. Keys issued before scoped self-serve creation may carry legacy scope names (e.g. productions:trigger, productions:cancel, webhooks:manage, performance:read); these are still accepted and map to their canonical equivalents (productions:write, webhooks:write, analytics:read).

Rotating a Key

Rotate a key when you suspect it has been compromised, or as part of regular security hygiene. In the Studio Console you rotate with zero downtime by creating a replacement before retiring the old key:

1. Create key with the same scopes as the key you are replacing.
2. Deploy the new key to your application.
3. Once traffic is flowing on the new key, Revoke the old one.

Both keys are valid in the meantime, so there is no downtime. Revocation takes effect immediately — any request using a revoked key receives 401 Unauthorized.

Error Responses

401 Unauthorized

Returned when the API key is missing, malformed, or revoked.

{
  "error": "UNAUTHORIZED",
  "message": "API key is missing, invalid, or has been revoked."
}

Common causes:

• X-API-Key header omitted from the request
• Key has been revoked — by you in the Studio Console or by an administrator
• Key was revoked by an administrator

403 Forbidden

Returned when the key is valid but lacks permission for the requested operation.

{
  "error": "PERMISSION_DENIED",
  "message": "Your API key does not have the required scope for this endpoint."
}

Common causes:

• API key scopes do not include the required scope for the endpoint
• accountId in the request path is not in the key’s PermittedAccountIds
• Partner account is not in Active status

Security Best Practices

1. Never embed API keys in client-side code — keys should only appear in server-side environments.
2. Use environment variables — store your key in JARAI_API_KEY or your platform’s secret manager.
3. Rotate keys regularly — create a replacement key and revoke the old one for zero-downtime rotation.
4. Monitor for key scanning — JARAI detects burst authentication failures (10+ within 60 seconds from one IP) and alerts the platform operator.
5. Use least-privilege scopes — when you create a key, select only the scopes your integration needs. The default read-only set is a good starting point.

Next Steps

• Production Lifecycle — trigger and manage productions
• Error Handling — understand the full error envelope and all error codes
• Rate Limiting — understand rate limits and how to stay within them