Authentication

An SDK session access token, issued by login, carries token_use: "session". It resolves as the user who logged in, with their role in the project checked again on every call.

A key cannot mint a key, so a user token is the credential for key management: it is minted where who you are is known. If a key could mint a key, revoking the first would not contain the damage.

Do not embed a user token in a service, because it expires with the session and carries the person's scope rather than the job's.

OAuth is covered in OAuth 2.1, which publishes the discovery documents and the seven fabric: scopes.

Only a SHA-256 hash of the secret is stored, so the gateway can verify a key it is shown and can never reproduce one. There is no recovery endpoint and no rotation endpoint.

Without grants, the key gets the default set for the creator's role. In the current gateway source an OWNER, ORG_ADMIN or PROJECT_ADMIN key gets sixteen grants: the eight in the example above plus model.run, connector.run, connector.sync, connector.connect, flow.delete, kb.delete, table.read and table.write.

The example was captured before those were added. Org and project members get six (query.read, docs.read, orchestrate.read, agent.run, connector.run, connector.sync), and any other or unrecognised role gets query.read and docs.read.

An explicit list is honoured exactly, and a key can never do what its creator could not. Read the grants, not the role: a key created with {"grants":["fabric:query.read"]} held one grant and still reported "role": "OWNER", because the role is copied from the creator and the grants are not. Keep unattended keys narrow.

Listing needs project_id as a query parameter, and revoking needs it plus the key id. A missing project_id is refused 400 project_id query param required before authentication runs.

curl -sS "https://fabric.wexa.ai/v1/apikeys?project_id=proj_abc" \
  -H "Authorization: Bearer $USER_TOKEN"

curl -sS -X DELETE "https://fabric.wexa.ai/v1/apikeys/key_IEhcUZrVvqI9C9hOAkwA_yOM?project_id=proj_abc" \
  -H "Authorization: Bearer $USER_TOKEN"

The list returns keys, each with id, name, scope, created_by, created_at, last_used_at and revoked, and never the secret. Revoked keys stay listed, so the record of what existed survives.

A key with no recent last_used_at is cheap to revoke; a revoked key that keeps being used shows which caller still holds the old secret. Revoke answers {"ok": true} and takes effect on the next request.

The key id is checked against the project's own list first, so an admin cannot revoke another project's key by guessing its id: an id not in this project answers 404 no such API key in this project, whether it exists elsewhere or not.

To rotate a key, create the replacement with the same grants if the old key was deliberately narrow, deploy the new secret to every caller until last_used_at stops moving on the old key, then revoke the old one. Revoking first takes the integration down for the length of the deployment.

Creation and revocation append the audit events apikey.created and apikey.revoked, recording the actor, their role, the key id and the project. Read them at GET /v1/audit; lifecycle and audit describes the record.

Every call then acts with the user's role in that project. When another process needs its own token lifecycle, POST /v1/auth/connect-project with a live session as the bearer returns a second session with its own refresh token (SDK: connectProject / connect_project). That separates refresh-token ownership only; requests still use Authorization: Bearer <credential>.

GET /v1/auth/my-projects lists the same projects from a session, and GET /v1/codesync/names returns org_name and project_name for any credential.

The same person on the same project ends up with different grants depending on the credential. Read back from GET /v1/whoami for one OWNER:

Grants gate the call, not the listing. A credential without a grant still sees every tool in tools/list, and is refused when it calls one: error (S2:resolve-scope): token missing required grant "…".

A refusal looks like this, and the WWW-Authenticate header points a client at where to authenticate. On a project-scoped connect URL it names /.well-known/oauth-protected-resource/mcp/proj_abc123 instead.

HTTP/1.1 401 Unauthorized
Www-Authenticate: Bearer resource_metadata="https://fabric.wexa.ai/.well-known/oauth-protected-resource"

{"error":"invalid_token","error_description":"missing bearer credential"}

A mistyped key that no longer starts with fab_sk_ falls through to the JWT checks and comes back as token invalid, while a revoked key gets api key invalid or revoked. Those two strings tell "wrong secret" from "wrong kind of secret".

Both SDKs map every one of these to AuthError; errors and retries covers the rest.

Two limiters exist, and conflating them leads to wrong retry behaviour.

A per-key limit of 60 requests per minute, in a fixed one-minute window counted per key id, applies only to POST /v1/agents/{agentflowId}/chat/completions. The 61st call is refused with 429, Retry-After: 1 and the OpenAI error shape ("code":"rate_limited"), not Wexa's.

Every other route is governed by the project and organization quota windows: 120 requests per project and 600 per organization in a sliding 60-second window by default, and 0 means unlimited. They answer Wexa's own body, S3:rate-quota, with a Retry-After carrying the real seconds remaining. Usage, quota and billing covers configuring them.

Some routes take no bearer credential, and not all are unauthenticated in the same way:

POST /oauth/authorize is authenticated, but by a user_token form field, falling back to the Authorization header only if the field is empty, because a browser consent screen posts it. With neither it answers 401 consent requires a valid Fabric user token.

• Credential management: who should hold a key, from an administrator's point of view.
• OAuth 2.1: registration, authorization, token and discovery endpoints.
• Errors and retries: what each refusal means and which are worth retrying.