Authentication

All Rekord API requests require authentication. This page covers how to authenticate and the permission model that governs access.

API tokens

Every request must include a valid API token in the Authorization header using the Bearer scheme:

Authorization: Bearer <your-api-token>

API tokens are scoped to a single workspace. The token determines which workspace your request operates in and what permissions you have. Tokens can be created and managed through the Rekord dashboard.

Token types

Rekord supports two types of API tokens:

Type	Purpose	Typical use
User token	Acts on behalf of a specific user	Dashboard integrations, manual workflows
Service token	Acts on behalf of an application	Automated pipelines, third-party integrations

Service tokens are recommended for production integrations. They are not tied to an individual user account and do not expire when a team member leaves.

Scopes

Tokens carry scopes that restrict which operations they can perform. Common scopes include:

Scope	Grants access to
models:read	Read model definitions
models:write	Create and update models
records:read	Read records
records:write	Update and delete records
contributions:read	Read contributions
contributions:write	Ingest contributions
contexts:read	Read decisioning contexts
contexts:write	Create and manage contexts
rules:read	Read rule definitions and evaluations
rules:write	Create and manage rules

Request the minimum set of scopes your integration requires.

Rate limiting

The API enforces rate limits per workspace. When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

Rate limits are applied at the workspace level, not per token. Multiple tokens in the same workspace share the same quota.

When rate limited, the response looks like:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 30 seconds."
  }
}

Use exponential backoff with jitter and respect the Retry-After header for production integrations.

Internal endpoints

Endpoints under the /internal/ path prefix are reserved for platform services. Requests to /internal/ paths with a consumer API token are rejected with 403 Forbidden. These endpoints are not documented in the public API reference and should not be depended on.

If you receive a 403 Forbidden error, check that your token has the required scopes and that you are not attempting to access an internal endpoint.

Error responses

Authentication failures return standard HTTP status codes:

Status	Meaning
401 Unauthorized	Missing or invalid token
403 Forbidden	Token is valid but lacks the required scope, or the endpoint is internal-only
429 Too Many Requests	Rate limit exceeded