> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate Metal API requests with API keys.

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:

| Credential | Header              | Description                                  |
| ---------- | ------------------- | -------------------------------------------- |
| Client ID  | `x-metal-client-id` | Public identifier for the key.               |
| Secret key | `x-metal-api-key`   | Secret value that authenticates the request. |

Send both headers on every request:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.metal.ai/v1/companies \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"
```

<Warning>
  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.
</Warning>

## Create a key in the app

Create your first API key from the Metal app. You need an admin role to manage keys.

<Steps>
  <Step title="Open API & MCP Access">
    In the Metal app, go to **Settings → Organization → API & MCP Access**.

    <Frame caption="The API & MCP Access page lists your organization's keys.">
      <img src="https://mintcdn.com/metal-05dd0988/kWbcLNNTbUpq7lH_/images/api-keys-list.png?fit=max&auto=format&n=kWbcLNNTbUpq7lH_&q=85&s=0d5827973f094476ac7e30370051aac5" alt="Metal settings page showing the API Keys table with name, client ID, key last four, and created date columns" width="2108" height="1968" data-path="images/api-keys-list.png" />
    </Frame>
  </Step>

  <Step title="Create a key">
    In the **API Keys** card, click **Create API Key**, enter a descriptive **Name** (for example, "Production sync"), and click **Create**.

    <Frame caption="Give the key a descriptive name.">
      <img src="https://mintcdn.com/metal-05dd0988/kWbcLNNTbUpq7lH_/images/api-keys-create-dialog.png?fit=max&auto=format&n=kWbcLNNTbUpq7lH_&q=85&s=b914fba3402d7f1b3a4bd352334afc30" alt="Create API Key dialog with a name input and a Create button" width="2108" height="1968" data-path="images/api-keys-create-dialog.png" />
    </Frame>
  </Step>

  <Step title="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.

    <Frame caption="Copy the Client ID and API Key. The secret is shown only once.">
      <img src="https://mintcdn.com/metal-05dd0988/kWbcLNNTbUpq7lH_/images/api-keys-created.png?fit=max&auto=format&n=kWbcLNNTbUpq7lH_&q=85&s=47ff9a807c4447782db006ec1fe99518" alt="Created key dialog displaying the Client ID and API Key values with copy buttons" width="2108" height="1968" data-path="images/api-keys-created.png" />
    </Frame>

    <Warning>
      This is the only time the **API Key** secret is shown. If you lose it, delete the key and create a new one.
    </Warning>
  </Step>
</Steps>

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 review and revoke keys programmatically with the [API keys endpoints](/api-reference/introduction):

* `GET /v1/keys` lists every key in your organization. Secrets are never returned again, only metadata such as `name` and `keyLastFour`.
* `DELETE /v1/keys/{key}` revokes a key immediately. Revoked keys stop working within a short cache window.

<Note>
  Keys are created in the Metal app, not through the API. Use the app to create a key, then manage its lifecycle here.
</Note>

## Best practices

<CardGroup cols={2}>
  <Card title="Use separate keys per integration" icon="layer-group">
    Create a distinct key for each integration or environment so you can rotate or revoke them independently.
  </Card>

  <Card title="Rotate regularly" icon="arrows-rotate">
    Create a new key, deploy it, then delete the old one to rotate without downtime.
  </Card>

  <Card title="Store secrets securely" icon="vault">
    Keep keys in a secret manager or environment variables, never in source control.
  </Card>

  <Card title="Scope by purpose" icon="tag">
    Name keys after the integration that uses them so you can audit and revoke precisely.
  </Card>
</CardGroup>

## Errors

If credentials are missing or invalid, the API responds with `401 Unauthorized`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "error": "invalid api key or clientId" }
```

See [Errors](/guides/errors) for the full list of status codes and how to handle them.