YaqeenDocs
Back to Yaqeen

How-to guide

Authentication

How people sign in with a session and how systems call the API with a key.

This guide shows how to sign in, how to create an API key, and what each key can do. People use a session. Systems use a key. You need an admin account to create keys.

Sign in as a person#

  1. Send GET /api/v1/auth/csrf/. The response sets a CSRF cookie. CSRF is a check that blocks requests from other sites.
  2. Send POST /api/v1/auth/login/ with username and password. The response sets a session cookie and returns your username and role.
  3. Send the cookie on every call. For every write (POST, PUT, PATCH, DELETE), also send the CSRF token in the X-CSRFToken header.

Sign-in is limited. The limits are 10 a minute per client, 5 a minute per username and address, and 20 an hour per username. Past a limit the answer is 429 with Retry-After. A wrong password gives 401 bad_credentials. Passwords need at least 12 characters.

Sign in with Google#

When Google sign-in is switched on for your deployment, the sign-in page shows a Google button. The browser gets a signed token from Google and sends it to POST /api/v1/auth/google/ as {"credential": "..."}. The API checks the token with Google's library, then finds the person by Google's own account id. It never matches by email.

  • A new person gets an account that is switched off. The answer is 403 account_pending. An admin switches it on and sets the role, as in Invite users and set roles.
  • A known, active person gets a session. The answer is 200 with username and role, as for a password sign-in.
  • A switched-off account answers 403 account_off.
  • An email that already has a password account answers 409 email_in_use. Accounts are never linked by email, because anyone who controls that Google address could take the account over. Ask an admin to link it.
  • A token Google does not accept, or an email Google has not confirmed, answers 401 google_failed.
  • Google sign-in is not set up answers 404 google_off.
  • Google cannot be reached answers 503 google_unavailable. The API waits at most 5 seconds for Google's public keys and keeps a good answer for 10 minutes. It never lets anyone in without checking the token.

The limit is the same as for a password sign-in: 10 a minute per client. Password sign-in still works. A Google account has no password until an admin issues a reset link.

Sign up with a username and password#

Anyone can ask for an account. Send POST /api/v1/auth/signup/ with username, email and password. No sign-in is needed, and the call does not sign the person in.

json
{ "username": "noor.khan", "email": "noor.khan@example.com", "password": "a-long-unusual-phrase-7" }

The answer is 201 with {"username": "noor.khan", "status": "waiting_for_approval"}. The account is switched off, has the role reviewer, and cannot sign in until an admin switches it on and chooses its role, as in Invite users and set roles.

  • A username needs at least 3 characters and cannot contain @. Google accounts use their email as the username, and without this rule a stranger could take an address first and make its real owner's Google sign-in fail. A taken username answers 409 username_taken, whatever the letter case.
  • The email is not confirmed. An admin treats it as a claim.
  • The password follows the same rules as everywhere else, so a weak one answers 400 invalid.
  • Sign-up is limited to 5 an hour per client. When too many accounts are already waiting, new sign-ups pause and the answer is 503 signups_paused. The same pause stops new Google accounts. People who already have an account are not affected.
  • The audit log records that a sign-up was requested with the user id only. It never holds the email or the username.

Create a key for a system#

An admin sends POST /api/v1/keys/:

json
{ "name": "erp", "scopes": ["read", "decide"], "days": 90, "rate_per_minute": 120, "allowed_ips": ["203.0.113.0/24"] }
FieldValues
nameRequired. Up to 60 characters.
scopesOne or more of read, decide, ingest, scim, mcp.
daysHow long the key lasts, 1 to 365.
rate_per_minuteCalls a minute, 1 to 6000. The default is 120.
allowed_ipsUp to 20 addresses or ranges, such as 203.0.113.7 or 203.0.113.0/24. The key works only from these. An empty list means any address. A call from another address answers 403.
sandboxtrue makes a sandbox key. The default is false.

The response contains the key. It starts with yq_live_. The key is shown once. Yaqeen stores only a hash, so it cannot show the key again. Send the key as a bearer token:

bash
curl https://api.example.test/api/v1/holds/ -H "Authorization: Bearer yq_live_..."

A key does not need a CSRF token. Give each system its own key, with only the scopes it uses, so one leak reaches one system. List the server addresses when they are fixed. Rotating a key keeps its scopes, rate and address list.

What each scope allows#

A key can only do what its scopes allow. The key also acts with a role. The role is the highest one that the scopes map to, so a key never does more than that role could.

ScopeRole it acts asAllows
readReviewerGET, HEAD and OPTIONS requests only. It never posts a decision.
decideReviewerGET requests, and the decision endpoints for holds, bulk decisions and appeals.
ingestAdminGET requests, and POST /api/v1/ingest/feed/.
mcpReviewerPOST /api/v1/mcp/ and nothing else: twelve read-only tools for an AI client. See Connect Claude and Codex.
scimAdminThe SCIM user endpoints under /api/v1/scim/v2/ and nothing else. POST /api/v1/scim/v2/Users needs a role (reviewer or admin). There is no default role.

A GET request also needs the role to be high enough. For example, GET /api/v1/audit/ needs the reviewer role, so a key with only read gets 403. A key with only read also gets 403 on the audit export, case exports, ops/kpis/, ops/monitoring/, ops/weekly-report/, ops/label-audit/, queue/workload/, GET /api/v1/policy/ and onboarding/. It can still read /api/v1/policy/proposals/. A key with the decide scope keeps the access it had. See Roles and permissions.

A key can never reach users, keys, webhooks, privacy, usage or sandbox endpoints, whatever its scopes. A key whose only scope is scim cannot reach anything outside SCIM.

Sign in from Claude or Codex (OAuth)#

A person can also connect Claude or Codex without a key. The client sends them to a Yaqeen sign-in page, they sign in and press Allow, and the client gets an access token for that person. Only reviewers and admins can do this, and a merchant account is refused. The steps are in Connect Claude and Codex.

  • The endpoints are /api/v1/oauth/authorize/, token/, register/ and revoke/. Clients find them at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.
  • PKCE with S256 is required.
  • The access token lasts 60 minutes. The refresh token lasts 30 days and works once. An old refresh token used again revokes all of that person's tokens for the client.
  • The token works at /api/v1/mcp/ only. It does not open any other endpoint. Yaqeen stores only its hash.
  • A person who has not disconnected the app skips the Allow page the next time.

Limits on a key#

Each key has its own limit, set by rate_per_minute. Your organization also has a daily call limit in its plan (50,000 calls a day by default). When a key is over a limit, the answer is 429 and the Retry-After header gives the seconds to wait. See Rate limits and pagination.

Rotate and revoke a key#

  • Send POST /api/v1/keys/{id}/rotate/ to make a new key with the same scopes. Add {"overlap_hours": 168} to choose how long the old key keeps working: 0 stops it now, 24 (the default) keeps it for one day, 168 for seven days. Any other value answers 400 bad_overlap. The answer has the new key, shown once.
  • Send DELETE /api/v1/keys/{id}/ to revoke a key now. It stops working at once.
  • GET /api/v1/keys/ lists the keys, newest first. Each row has created_at, created_by, sandbox, last_used_at and a status: active, expiring (it ends within 7 days), expired or revoked. last_used_at is written at most once every 5 minutes, so it can be a few minutes behind.

An admin can do all of this in the dashboard under Settings, API keys. The key is shown once, and the panel cannot be closed by accident until the admin says it was saved.

Sandbox keys#

A sandbox key starts with yq_test_ and only sees the sandbox. Create the sandbox first, or the request fails with 409 no_sandbox.

If it does not work#

You seeCauseFix
401 with a Bearer challengeThe key is wrong, expired or revoked.Check the key. Create a new one if needed.
403 and "This key's scopes do not allow that."The scope or path is not allowed for keys.Add the scope, or use a session for that call.
403 and "You do not have permission"The key's role is too low for the endpoint.Use a scope that maps to a higher role.
429The key or the plan limit is used up.Wait for Retry-After seconds.

Next steps#

Up Down to moveEnter to openEsc to close