API keys
API keys authenticate specific external clients to a single surface. Each key is bound to one surface at creation time and carries a secret the client presents on every request. Use this page to view, issue, revoke, and rotate the keys that authenticate external clients to a specific surface.
Overview
Surface-scoped API keys let you identify and control individual clients independently. Creating a separate key per client means you can revoke one without affecting others. The key secret is stored encrypted and can be revealed from the key detail page.
API keys differ from Secrets. A secret stores a raw credential value that the gateway uses internally, for example a token or password for header injection or transit point target authentication. An API key authenticates an external client calling the gateway.
For a step-by-step walkthrough of adding API key authentication to a surface, see Restrict surface access with API key authentication.
Fields
| Field | Required | Description |
|---|---|---|
| Surface | Yes | The surface this key grants access to. Selected from a dropdown at creation time. Cannot be changed after the key is created. |
| Client ID | Yes | A label identifying the external client, for example mobile-agent or partner-service. Displayed in logs and the API keys list. |
| Key ID | Auto-generated | Unique identifier for the key. Shown after creation. |
| Secret | Auto-generated | The credential value the client presents on every request. Displayed in the creation modal and retrievable from the key detail page using the reveal toggle. |
Key states
| Status | Description |
|---|---|
| Active | The key is valid. Clients presenting this key to the bound surface are authenticated. |
| Revoked | The key has been suspended. Clients presenting this key receive an authentication failure. The key record is retained. |
Operations
Create an API key
In the sidebar, select Secrets, then select the API Keys tab, then select New API Key. Choose the surface from the Surface dropdown, then enter a Client ID. Select Create. Copy the Secret from the confirmation modal. You can also retrieve it later from the key detail page using the reveal toggle.
Never hardcode the API key secret in source code or configuration files. Store it in a secrets manager or encrypted environment variable. If you suspect the value has been exposed, revoke the key immediately.
Revoke a key
Select Revoke on the key row. The key status changes to Revoked and it can no longer be used for authentication. The record is retained for audit purposes.
Rotate a key
Select Rotate on the key row. The current key is revoked and a new key is generated in a single operation. A modal displays the new Secret. Copy it immediately. The new key is bound to the same surface and Client ID as the original.
Delete a key
Select the delete icon on the key row and confirm. Deletion is permanent. Delete revoked keys that are no longer needed to keep the list clean.
Related
- Restrict surface access with API key authentication: end-to-end guide adding API key auth to a surface.
- Secrets: encrypted credential values used in surface configuration and transit point authentication.
Glad to hear it! Please tell us how we can improve more.
Sorry to hear that. Please tell us how we can improve.
Thank you for sharing your feedback so we can improve your experience.