Docs/Getting Started

Authentication

Secure your API requests with a bearer token or the X-API-Key header.

Every request needs an API key sent in a header. You can send it in one of two ways.

Header	When to use it
`Authorization: Bearer YOUR_API_KEY`	Recommended. This is what the OpenAI SDKs send.
`X-API-Key: YOUR_API_KEY`	An alternative if your HTTP client makes the Authorization header awkward.

Keep keys on the server

Never put an API key in browser or mobile code: anyone can read it. Keep it in an environment variable and call Tarqa from your backend.

A key belongs to one workspace

A key is tied to the workspace that was active when you created it, and that never changes. There's no header or parameter that makes a key act as another workspace.

	Personal key	Team key
Created from	Your personal workspace	A team workspace
Who can use it	Only you	Every member of that team
Whose plan it uses	Your own plan (Free / Starter / Pro)	The team owner's plan
Who can see it	Only you	The team's owner and admins
If revoked	Only your integrations stop	Every member's integration stops at once

The key list in your dashboard shows which workspace each key belongs to. Check it before putting a key into production: a personal key can't be moved to a team later.

Rotate a key without downtime

1
Create a new key
Create it in the same workspace as the old one.
2
Deploy it
Update every service that uses the old key.
3
Confirm traffic
Check the new key's analytics to see that requests are flowing.
4
Revoke the old key
Only now, once nothing uses it anymore.

Revoking takes effect within about 5 minutes, because auth results are cached briefly (disabled and expired keys are never cached). There's no grace period: once that happens, the key returns 401 on its next request.

Expiring keys

If you set expires_in_days when creating a key, that's a hard expiry. The first request after that time fails with 401 "API key has expired" and the key is switched off. There's no renewal, and no warning beyond an entry in your activity log, so put the rotation date in your calendar.

FAQ

I get 401 on every request. What's wrong?

The key is missing, mistyped, revoked or expired. Check the header name (Authorization: Bearer … or X-API-Key) and look the key up in your dashboard's key list.

Can one key work for both my personal workspace and a team?

No. Create a separate key in each workspace.

How fast does revoking a key take effect?

Within about 5 minutes.