API keys

Your code authenticates to Toggld with a credential in the Authorization: Bearer header. Each credential belongs to one environment of one workspace. The credential selects both, so you never send them in a request.

Credential typesCopy Anchor Link

Choose the least powerful credential that does the job. For a backend that only reads flags, use a server SDK key.

Where to find themCopy Anchor Link

Open Settings → API Keys. The page shows the API endpoint to use with your SDK, then one section per environment. Each section has:

• One Public token, with a Copy button.
• A list of Secret API keys, with the name, type, a masked prefix, and the creation date.

Owners, admins, and members can view and manage credentials. Only owners and admins can create management keys, because a management key can also change environments and keys. Readers cannot see this page.

Create a secret keyCopy Anchor Link

1. Open Settings → API Keys.
2. In the section for the environment that you need, select Create key.
3. Enter a Key name, such as Checkout API production. Only your team sees it.
4. Under Access, choose Server SDK key or Management key. Only owners and admins see Management key.
5. Select Create key.
6. Copy the key and store it in your secret manager.

Set the key in your server environment, not in code:

TOGGLD_SDK_KEY=ffk_YOUR_SECRET_KEY

Public tokensCopy Anchor Link

Every environment has exactly one public token. Toggld creates it for you. Public tokens are safe to embed in client-side code, because they can only evaluate flags. See Browser.

const PUBLIC_TOKEN = "ffp_YOUR_PUBLIC_TOKEN";

You cannot rotate or revoke a public token. It stops working only when you delete its environment. Because anyone can read evaluated values with it, never put secrets in variant values or flag metadata.

Rotate a secret keyCopy Anchor Link

Rotate keys regularly, and at once if a key may be exposed.

1. Create a new key in the same environment, with the same access.
2. Deploy the new key to every application that uses the old one.
3. Confirm that the applications work with the new key.
4. Delete the old key.

Delete (revoke) a secret keyCopy Anchor Link

1. Open Settings → API Keys.
2. Find the key and select the delete icon.
3. In Delete this secret key?, select Delete key.

Applications that use the key lose API access. You cannot undo the deletion. On the hosted API, a deleted key can keep working for up to 60 seconds while edge caches expire.

If a key leaksCopy Anchor Link

1. Create a replacement key and deploy it.
2. Delete the leaked key.
3. Check the audit log for changes made with the key. The actor of each event shows the API key ID.

Never send keys to Toggld support.

Management keys and environmentsCopy Anchor Link

A management key reads and writes the flag configuration of its own environment. Some operations still reach the whole workspace:

• Changes to shared flag fields (name, description, tags, metadata) apply to every environment.
• Deleting a flag removes it from every environment.
• Segment changes apply to every environment.
• A management key can create and delete environments, and create and revoke keys for any environment.

Treat every management key as workspace-wide access.

Manage keys with the APICopy Anchor Link

Key endpoints require a management key.

Create a key. environment is required. It is the key of the environment that the new key belongs to:

curl https://api.toggld.io/api/v1/keys \
  -H "Authorization: Bearer ffk_YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "evaluation", "name": "Checkout API", "environment": "production" }'

The response (HTTP 201) includes token, the full secret key. It is the only time the API returns it.

List keys. The response shows each key's prefix, never the full key:

curl https://api.toggld.io/api/v1/keys \
  -H "Authorization: Bearer ffk_YOUR_MANAGEMENT_KEY"

Revoke a key by its id:

curl -X DELETE https://api.toggld.io/api/v1/keys/KEY_ID \
  -H "Authorization: Bearer ffk_YOUR_MANAGEMENT_KEY"

List the public tokens of every environment:

curl https://api.toggld.io/api/v1/public-tokens \
  -H "Authorization: Bearer ffk_YOUR_MANAGEMENT_KEY"

See Authentication for which credential each endpoint accepts.