Public API: Authentication

The public API uses service tokens — scoped, revocable Bearer credentials bound to an organisation. They authenticate external integrations, CI pipelines, and any automation that needs to manage AvsB resources without a human session.

Token format

Every service token starts with the prefix avsb_svc_ and contains 32 random bytes of entropy, base64url-encoded:

1avsb_svc_abc12345_KMv3l4...VeryLongRandomString

Tokens are shown once, at creation time. AvsB stores only a SHA-256 hash of the secret. You must save the token somewhere safe at creation; if you lose it, rotate or revoke and create a new one.

Creating a token

Scopes

Scopes are the token's permission system. Each scope is read/write per resource family. The auth layer rejects requests with a missing scope using a 403 response and a structured scope_missing error code naming the missing scope.

The complete scope vocabulary:

1org:read              org:write
2projects:read         projects:write
3experiments:read      experiments:write
4flags:read            flags:write
5audiences:read        audiences:write
6segments:read         segments:write
7metrics:read          metrics:write
8results:read          (no write — results are computed, not authored)
9members:read          members:write
10roles:read            roles:write
11webhooks:read         webhooks:write
12integrations:read     integrations:write
13tokens:read           tokens:write
14audit:read            (no write — audit log is system-authored)
15admin:*               (superuser wildcard — covers everything)

Rotating a token

Rotation issues a new secret while preserving the token's identity (id, name, scopes, audit-log references). The old secret stops working immediately. Use rotation when:

• A developer who knew the secret leaves the team.
• A secret may have leaked (commit history, logs, screenshots).
• Routine credential hygiene — quarterly or per security policy.

Rotate from the dashboard API Tokens tab (Rotate button on each row), or via the API:

1curl -X POST https://app.avsb.cloud/api/orgs/<orgId>/tokens/<tokenId>/rotate \
2  -H "Authorization: Bearer avsb_svc_..."

Existing integrations using the old secret must be updated to the new secret in lockstep. Plan rotation during a low-traffic window.

Revoking a token

Revocation is a soft-delete: the token row is preserved (so audit history continues to resolve to it), but every request authenticating with it returns 401 immediately. There is no undo.

Revoke from the dashboard or via DELETE on the token resource:

1curl -X DELETE https://app.avsb.cloud/api/orgs/<orgId>/tokens/<tokenId> \
2  -H "Authorization: Bearer avsb_svc_..."

Expiry

Tokens can be created with an optional expiry up to one year out. Expired tokens fail with a 401 and a token_expired error code. The dashboard surfaces tokens expiring in the next 14 days as warnings on the API Tokens tab — set a calendar reminder, or rotate ahead of time.

Last-used tracking

Every authenticated request updates the token's last-used timestamp, IP address, and user-agent. The API Tokens dashboard tab shows this metadata so you can identify dormant tokens and revoke them, or trace which client is using which token.

Security recommendations

• Use scoped tokens, not admin:*. Limit blast radius by granting only the scopes the integration genuinely needs.
• Set expiry. Default to one year. Rotate ahead of expiry rather than letting tokens lapse and breaking integrations.
• One token per integration.Don't share tokens across services. The last-used metadata is only useful if a token uniquely identifies its caller.
• Store in a secrets manager. Never commit tokens to version control. Use environment variables wired from your secrets backend.
• Revoke on suspicion. A token revocation is cheap; investigating a credential leak after the fact is not.