JARAI Developers

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 follow the format jarai_{base64url}. The jarai_ prefix allows automated secret scanners to identify leaked keys. Example:

jarai_dGhpcyBpcyBhbiBleGFtcGxlIGtleQ

Your API key is returned once during partner verification (GET /v1/partners/verify) and again when you rotate keys (POST /v1/partners/keys/rotate). It cannot be retrieved after that — store it securely.

Passing Your API Key

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

curl https://apim-jarai-prd.azure-api.net/v1/accounts \
-H "X-API-Key: jarai_your_api_key_here"

Scoped Keys

API keys can be scoped to restrict access to specific endpoints. Scopes are configured by your JARAI account manager — they cannot be modified through the API.

ScopeEndpoints
productions:triggerPOST /v1/accounts/{accountId}/productions
productions:readGET /v1/productions/*
productions:cancelDELETE /v1/productions/{productionId}
deliverables:readGET /v1/productions/{productionId}/deliverables
performance:readGET /v1/productions/{productionId}/performance, GET /v1/partner/usage
accounts:readGET /v1/accounts*
webhooks:managePOST/GET/DELETE /v1/webhooks*

If PermittedScopes is null on your API key, all scopes are granted (full access). When scopes are set, any request to an out-of-scope endpoint returns 403 PERMISSION_DENIED.

Key Rotation

Rotate your API key when you suspect it has been compromised, or as part of regular security hygiene:

curl -X POST https://apim-jarai-prd.azure-api.net/v1/partners/keys/rotate \
-H "X-API-Key: jarai_your_current_key_here"

After rotation:

  • The new key is active immediately.
  • The old key remains valid for a 24-hour grace period, then is permanently revoked.
  • The new key inherits the same scopes and account permissions as the old key.

Key rotation requires SelfServeKeyRotationEnabled = true on your partner account. If self-serve rotation is disabled, contact JARAI support.

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 rotated and the old key’s 24-hour grace period has expired
  • 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 — the 24-hour grace period allows 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. Request scoped keys — if your integration only needs read access, ask your JARAI account manager to restrict your key’s scopes.

Next Steps