togglddocs
Dashboard
GuidesAPI reference
API keys

Create an API key

POST
/api/v1/keys

Creates a secret API key for one environment. environment is required.

The response includes the token. This is the only time the API returns it, so store it securely.

Requires a management key.

Returns 404 if the environment does not exist.

Authorization

bearer
headerAuthorizationBearer <token>

Send a credential in the Authorization header: Authorization: Bearer <token>. Each credential belongs to one environment of one workspace, so the API never takes a workspace or environment in the URL.

  • Management key (ffk_…, secret): manages flags, segments, environments, and API keys, and reads the audit log and analytics. It can also do everything an evaluation key can.
  • Evaluation key (ffk_…, secret): for server SDKs. It evaluates flags, reads flag definitions for local evaluation, and sends telemetry.
  • Public token (ffp_…, not secret): for browser and mobile apps. It evaluates flags through OFREP and sends telemetry. It cannot read flag definitions.

Keep secret keys on your server. A 401 response means the credential is missing or not valid. A 403 response means the credential is valid but its role cannot perform the operation.

Request Body

application/json
  1. body

The API key to create.

role*string

What the key can do. management: manage the workspace through the management API, and evaluate flags. evaluation: evaluate flags, read flag definitions for local evaluation, and send telemetry.

Value in"management""evaluation"
name?string

A label for the key, such as the service that uses it.

environment*string

The key of the environment the API key belongs to, such as production. Required.

Length1 <= length

Response Body

Created

application/json
  1. response

A new secret API key, including its token. The token is shown only once.

id*string

The API key ID, such as key_…. Use it to revoke the key.

tenantId*string

The ID of the workspace that owns the key.

environmentId*string

The ID of the environment the key belongs to.

name?string

A label for the key.

role*string

What the key can do. management: manage the workspace through the management API, and evaluate flags. evaluation: evaluate flags, read flag definitions for local evaluation, and send telemetry.

Value in"management""evaluation"
prefix*string

The first characters of the token, so you can recognize the key. It is not enough to authenticate.

createdAt*string

When the key was created, as an ISO 8601 timestamp.

token*string

The full secret token, which starts with ffk_. This is the only time the API returns it. Store it securely.

Example Request
curl -X POST 'https://api.toggld.io/api/v1/keys' \  -H 'Content-Type: application/json' \  -d '{  "role": "evaluation",  "name": "Checkout service",  "environment": "production"}'
Example Response
{  "id": "key_8a1d4c7e-2b5f-4e9a-9c3d-6f0b1a2e4d8c",  "tenantId": "t_5b9e2c4a-8f1d-4a7c-b3e6-9d0c2f5a8b1e",  "environmentId": "env_3f6b2a9c-1d4e-4f7a-8b2c-5e9d0a1f3c7b",  "name": "Checkout service",  "role": "evaluation",  "prefix": "ffk_VIGOVS",  "createdAt": "2026-05-01T12:00:00.000Z",  "token": "ffk_VIGOVSCgpmV1QofLEofOmH2COc97pZW9K40xyIx0DCQ"}

List API keys GET

Returns every secret API key in the workspace, in all environments. The response never includes the tokens, only a short prefix of each. Requires a management key.

Revoke an API key DELETE

Permanently revokes a secret API key. Requests that use it then fail with `401`. It can take a short time for the key to stop working everywhere. Requires a management key. Returns `404` if no key has this ID.