Skip to main content
The Metal API uses API keys to authenticate requests. Each key belongs to a single organization, and every request is automatically scoped to that organization’s data. API keys are service-level, server-to-server credentials. They are not OAuth tokens and they do not impersonate each end user of a customer-built app. For per-user access from Claude, ChatGPT, or Cursor, use the Metal MCP server instead. See Choose the API or MCP for the two models side by side.

​
API key credentials

An API key has two parts that are always sent together: Send both headers on every request:
The secret key is returned only once, when the key is created. If you lose it, delete the key and create a new one. Never expose it in client-side code, browsers, or mobile apps. API keys are for server-to-server use only.

​
Create a key in the app

Create your first API key from the Metal app. You need the Admin role to create, list, or revoke keys.
1

Open API & MCP Access

In the Metal app, go to Settings → Organization → API & MCP Access.
Metal settings page showing the API Keys table with name, client ID, key last four, and created date columns

The API & MCP Access page lists your organization's keys.

2

Create a key

In the API Keys card, click Create API Key, enter a descriptive Name (for example, “Production sync”), and click Create.
Create API Key dialog with a name input and a Create button

Give the key a descriptive name.

3

Copy your credentials

Metal shows the new key’s Client ID (x-metal-client-id) and API Key (x-metal-api-key). Copy both and store them securely.
Created key dialog displaying the Client ID and API Key values with copy buttons

Copy the Client ID and API Key. The secret is shown only once.

This is the only time the API Key secret is shown. If you lose it, delete the key and create a new one.
The number of keys you can create depends on your plan. If you hit the limit, delete unused keys before creating new ones.

​
Manage keys

Keys are created, rotated, and revoked in the app. An Admin, or a member of the Metal team, manages them at Settings → Organization → API & MCP Access. GET /v1/keys/current reports which key a request is using, so you can confirm the credentials an integration holds:
The gateway also exposes GET, POST, and DELETE /v1/keys, but only to that signed-in session. API keys are rejected, so those endpoints aren’t part of the API reference: manage keys in the app.

​
Admin-only endpoints

Some endpoints also check the caller’s role as well as their credentials:
  • API key management: an Admin, or a member of the Metal team, signed in to the Metal app. API keys are always rejected, including keys an Admin created.
  • Schema and CRM configuration writes: an Admin signed in to the app, or an API key an Admin created. Keys created by other roles are rejected. Reads of the schema and of CRM configurations stay open to any member and any key.
A call that doesn’t meet the rule returns 403 Forbidden:
Read message for the text to show a user. details repeats it once per reason or per field. This body is different from the error body returned for authentication failures, and some resource-level refusals use the error body too, so handle the two shapes separately. See Errors.

​
Best practices

Use separate keys per integration

Create a distinct key for each integration or environment so you can rotate or revoke them independently.

Rotate regularly

Create a new key, deploy it, then delete the old one to rotate without downtime.

Store secrets securely

Keep keys in a secret manager or environment variables, never in source control.

Scope by purpose

Name keys after the integration that uses them so you can audit and revoke precisely.

​
Errors

If credentials are missing or invalid, the API responds with 401 Unauthorized:
If an API key calls an endpoint that requires a signed-in Admin, such as POST /v1/keys, the API responds with 403 Forbidden. That body carries code, message, and details rather than error; see Admin-only endpoints for the shape. See Errors for the full list of status codes and how to handle them.