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 key credentials

An API key has two parts that are always sent together:
CredentialHeaderDescription
Client IDx-metal-client-idPublic identifier for the key.
Secret keyx-metal-api-keySecret value that authenticates the request.
Send both headers on every request: 
curl https://api.metal.ai/v1/companies \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"
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 an admin role to manage 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
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
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
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 with the API

Once you have a key, you can manage keys programmatically with the API keys endpoints:
  • GET /v1/keys — list every key in your organization. Secrets are never returned again, only metadata such as name and keyLastFour.
  • POST /v1/keys — create a new key with a name. The response includes the one-time secret key.
  • DELETE /v1/keys/{key} — revoke a key immediately. Revoked keys stop working within a short cache window.

​
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: 
{ "error": "invalid api key or clientId" }
See Errors for the full list of status codes and how to handle them.