Authentication
How to send credentials, which credential each API surface accepts, and what 401 and 403 mean.
Every request, except the health checks, needs a credential in the Authorization header as a bearer token:
Authorization: Bearer ffk_YOUR_SECRET_KEYSend the header on every request. The API does not use cookies or query-string credentials.
Credentials
| Credential | Prefix | Role | How to get it |
|---|---|---|---|
| Server SDK key | ffk_ | evaluation | Settings → API Keys → Create key, with Server SDK key access |
| Management key | ffk_ | management | Settings → API Keys → Create key, with Management key access |
| Public token | ffp_ | evaluation, public | Settings → API Keys, one per environment |
See API keys for how to create, store, and revoke them.
The credential selects the workspace and environment
Each credential belongs to one environment of one workspace. The API reads both from the credential. You never put a workspace ID or an environment in the URL, the query string, or the body. This is why standard OpenFeature OFREP clients work with Toggld unchanged.
To work with several environments, use one credential per environment.
What each surface accepts
| Endpoints | Server SDK key | Management key | Public token |
|---|---|---|---|
POST /ofrep/v1/evaluate/flags/{key}, POST /ofrep/v1/evaluate/flags | Yes | Yes | Yes |
GET /sync/v1/flags | Yes | Yes | No (403) |
POST /v1/telemetry | Yes | Yes | Yes |
Management reads: GET on /api/v1/flags, /api/v1/tags, /api/v1/segments, /api/v1/environments, /api/v1/audit-log, and /api/v1/flags/{key}/analytics | No (403) | Yes | No (403) |
Management writes: POST, PUT, PATCH, and DELETE on /api/v1/... | No (403) | Yes | No (403) |
Credentials: /api/v1/keys and /api/v1/public-tokens | No (403) | Yes | No (403) |
GET /health, GET /ready | No credential needed |
The dashboard calls the same API for signed-in users. Dashboard readers can use the management read endpoints, but not the write or credential endpoints. Those permissions belong to dashboard sessions only. A server SDK key never gets management access.
401 and 403
| Status | Error | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | The credential is missing, malformed, unknown, or revoked. | Check the header format and the key. Create a new key if you lost it. |
| 403 | Forbidden | The credential is valid but cannot use this endpoint. For example, a server SDK key called the Management API, or a public token called the sync API. | Use a credential with the required role. |
{ "_tag": "Unauthorized", "message": "Missing or invalid credentials" }{ "_tag": "Forbidden", "message": "Management role required" }Repeated authentication failures from one IP address count against a separate rate limit of 20 failures per minute.
Revocation timing
When you delete a key, the API stops accepting it. On the hosted API, edge caches can accept a deleted key for up to 60 seconds. Clients that already downloaded a snapshot with local evaluation keep that snapshot.
Keep credentials safe
- Store secret keys in a secret manager or in server environment variables.
- Never put secret keys in browser code, mobile apps, logs, or source control.
- Use public tokens for client-side code.
- Never send credentials to Toggld support.