# API keys

> Field reference for surface-scoped API keys in the Agent Gateway dashboard: fields, key states, and lifecycle operations.
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.

## 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 shown only once at creation and stored encrypted.

API keys differ from [Secrets](/products/affinidi-trust-fabric/agent-gateway/reference/authentication/secrets.md). A secret stores a raw credential value (token, password) that the gateway uses internally, for example in 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](/products/affinidi-trust-fabric/agent-gateway/how-to-guides/access/restrict-surface-access-with-api-key.md).

## Fields

| Field | Required | Description |
| Surface | Yes | The surface this key grants access to. Set 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. |
| Labels | No | Optional key=value pairs for categorisation and filtering. Enter as comma-separated pairs, for example env=prod, team=platform. Searchable from 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. Shown once at creation time only. |

## 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. Select the surface and set a Client ID. Optionally add labels as comma-separated key=value pairs to categorise the key. Copy the Secret from the confirmation modal immediately; it is displayed only once.
Secret hygiene

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

Revoke the existing key, create a new key for the same surface and Client ID, share the new secret with the client, then delete the old revoked key once the client has migrated.

### 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](/products/affinidi-trust-fabric/agent-gateway/how-to-guides/access/restrict-surface-access-with-api-key.md): end-to-end guide adding API key auth to a surface.

- [Secrets](/products/affinidi-trust-fabric/agent-gateway/reference/authentication/secrets.md): encrypted credential values used in surface configuration and transit point authentication.