Authentication & API keys

The Partner API authenticates every request with an API key you create yourself in the Studio Console, under Settings → API Keys — there’s no registration form and no waiting for approval. You sign in with your JARAI account (Microsoft, Google, or email — the same account you use for the Console) and mint a scoped key in seconds. The key identifies your integration and scopes it to your account’s data.

🎬 Create and use an API key

Prefer to read? Open the step-by-step transcript

1. Sign in to the Studio Console and open Settings → API Keys.
2. Create an API key (name it for the integration that will use it) and choose its scopes.
3. Copy it once — store it in your own secret manager; JARAI shows it only at creation.
4. Send it on every request in the authentication header (exact header name + format are in the Developer Portal reference).
5. Rotate it periodically; revoke immediately if it leaks.

Before you start

Getting a key is identity-first and self-serve — there’s no separate API registration:

• You sign in to the Studio Console with your JARAI account — Microsoft, Google, or email. If your organisation already uses JARAI you’re ready; there’s nothing extra to register, and your keys live alongside the rest of your account settings.
• You need the Customer administrator role. Creating and revoking keys is available to customer administrators on your account. If you can sign in but can’t create a key, ask whoever administers your JARAI account to grant the role, or to create the key for you.
• No approval queue for keys. Keys are issued instantly, the moment you create them. Until your live access is approved they’re sandbox test keys — see Test keys & the sandbox for going live.

Creating a key

1. Open the Studio Console, sign in, and go to Settings → API Keys. Sign in with your JARAI account — Microsoft, Google, or email.

2. Create a key, give it a descriptive name (e.g. prod-ingest-service) so you can tell keys apart later, and choose its scopes — least-privilege by default; add write scopes only if your integration needs them.

3. Copy the secret once. It’s shown only at creation time. Store it in your own secret manager — never in source control, client-side code, or a shared doc.

Using a key

Send the key on every request in the authentication header. The exact header name and value format are documented in the Developer Portal reference (it’s the authoritative source — don’t hard-code an assumption from a blog post).

Keep keys server-side

An API key carries your account’s authority. Call the Partner API from your backend, never from a browser or mobile client where the key would be exposed. For end-user-facing flows, proxy through your own server.

Rotating & revoking

• Rotate keys on a schedule. Create the new key, deploy it, then revoke the old one — zero-downtime rotation.
• Revoke immediately if a key is exposed (committed, logged, leaked). A revoked key can keep authenticating for up to 5 minutes while a cached copy of its verification expires, so treat a leaked key as live for that long — revoke first, then rotate whatever it could reach.
• Use separate keys per integration/environment so you can revoke one without breaking the others, and so usage is attributable.

What a key can do

A key acts within your account’s scope and draws on its token allowance and billing. It cannot cross into other accounts’ data — the platform enforces account isolation server-side regardless of what a key requests.

Note

Auth failures return a structured error (an authentication error code + message). Handle 401/auth errors by checking the key is present, current, and sent in the correct header — see the reference for the exact codes.

Test keys & the sandbox

Until live access is approved, the keys you create in the Studio Console are test keys (prefixed jarai_test_). They’re scoped to your own sandbox accounts — the place to build and validate your integration without touching live distribution or spending beyond your account’s allowance.

When you’re ready to go live, press Request live access on Settings → API Keys and describe what you’ll build. JARAI reviews the request (the page shows it as pending until then). Once it’s approved, the keys you create on the same page are live keys (jarai_live_) — still self-serve, carrying the scopes you select, but operating against your live accounts. Keys you made before approval stay test keys.

How the sandbox behaves

There’s no separate sandbox host — you call the same /v1 endpoints with the same base URL. The behaviour is decided by your key:

• A jarai_test_ key returns synthetic responses flagged "sandbox": true. Triggering a production, listing accounts, fetching performance — all return realistic shapes, but nothing runs the real pipeline, publishes, or costs anything. It’s safe to script against in CI.
• A jarai_live_ key can still take a one-off sandbox response by sending the X-JARAI-Test: true header (when your account has test mode enabled) — handy for a smoke test against production without side effects.

Tip

Keep test and live keys in separate environments and separate secret stores. A request made with a jarai_test_ key only ever affects sandbox data.

Rate limits & tiers

Every key shares a per-partner request budget set by your tier. The limits are returned on each response in the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; exceeding them returns 429 Too Many Requests.

Tier	Requests/min	Requests/day	Daily productions per account
Free	10	100	3
Standard	60	2,000	20
Enterprise	300	Unlimited	Unlimited

Self-provisioned keys start on the Free tier. The budget is shared across all of a customer’s keys, so creating more keys doesn’t raise the limit. Read the live X-RateLimit-* headers and back off as X-RateLimit-Remaining approaches zero — the Developer Portal reference carries the authoritative limits.