Authentication

How EnfinitOS authenticates SDK and HTTP API calls — bearer tokens, scopes, rotation, and the sandbox vs. production split.

EnfinitOS authenticates every API call with a bearer token in the Authorization header.

Authorization: Bearer sk_live_...

Token shape and scope

Every token is scoped to a single tenant, and inside that tenant to a specific role:

Role	What it can do
tenant_admin	Everything inside the tenant.
tenant_operator	Run campaigns, send delivery events, manage rights.
tenant_reviewer	Read-only audit + compliance surface.
tenant_brand	Read-only access to brand-owned campaign records.
tenant_auditor	Read-only proof-pack and chain-verification surface.

Tokens are prefixed for hand-checking:

• sk_live_... — production traffic.
• sk_sandbox_... — sandbox tenant.
• sk_test_... — local test fixtures (no real backend).

A leaked production token gives an attacker the full surface that role allows. Treat tokens as production secrets — store them in a secrets manager, rotate them on a schedule, never commit them.

Token rotation

The platform supports overlapping tokens during a rotation window so there is never a moment when an operator’s automation is offline:

1. Generate a new token in the operator dashboard.
2. Roll your services onto it (rolling deploy, blue-green, etc.).
3. Wait until your observability shows zero traffic on the old token.
4. Revoke the old token.

The rotation window is at least 90 days by default; you can shorten it to a value you choose for compliance reasons.

Sandbox vs. production

Concern	Sandbox	Production
Base URL	https://sandbox.api.enfinitos.com	https://api.enfinitos.com
Token prefix	sk_sandbox_	sk_live_
Tenant data	Synthetic, resettable	Real, immutable
Proof chain	Signed by the sandbox verification key	Signed by the production verification key

The sandbox uses a separate signing key so any proof pack you fetch from sandbox cannot impersonate a production pack. The public half of both keys is published at docs.enfinitos.com/compliance/verification-keys.

Rate limits

Each tenant has a request quota set by its plan. The sandbox ships with a generous quota for evaluation; production quotas are finalised per plan at the April 2027 launch.

When a quota is exhausted the API returns 429 with a RATE_LIMITED error and a Retry-After header. Responses also carry rate-limit headers so you can track remaining quota, and the SDKs back off and surface a warning as you approach the limit.

Errors

All authentication errors follow the same envelope:

{
  "ok": false,
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Missing or invalid bearer token.",
    "requestId": "req_..."
  }
}

Possible codes:

Code	Meaning
AUTH_REQUIRED	No token.
AUTH_INVALID	Malformed or revoked token.
AUTH_SCOPE_INSUFFICIENT	Token is valid but lacks the role this endpoint requires.
AUTH_TENANT_SUSPENDED	Tenant is administratively paused.