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

# Create and manage Armature API keys for MCP access

> Create and manage bearer tokens that authenticate MCP clients with Armature. Each token is shown once and cannot be retrieved after creation.

API keys are bearer tokens that authenticate MCP clients against the Armature MCP endpoint at `/api/mcp`. Any MCP client — whether an AI agent, a CI pipeline, or a custom integration — includes the token in its HTTP request headers. Armature validates the token, identifies your organization, and enforces the role permissions that were active when the key was created.

## Token format

Every Armature API key follows this structure:

```text theme={null}
amt_<key-id>_<secret>
```

For example:

```text theme={null}
amt_abc123_xyz789abcdefghij...
```

The `amt_` prefix makes Armature tokens easy to identify in logs and secret scanners. The key ID portion (`abc123`) is stored in the dashboard and used to identify which key a request came from. The secret portion is never stored in plaintext — Armature stores only a secure one-way hash of it and cannot retrieve the original value.

## Creating an API key

<Steps>
  <Step title="Go to Settings → API keys">
    Open **Settings** in the Armature sidebar and select **API keys** from the section navigation.
  </Step>

  <Step title="Name the key">
    Enter a descriptive name in the **Key name** field. Choose a name that identifies the client or purpose, for example `prod-mcp-agent` or `ci-regression-runner`. A good name makes it easy to identify which key to revoke if a client is decommissioned.
  </Step>

  <Step title="Click Create key">
    Click **Create key**. Armature generates the token and displays the full `amt_...` value in a **New token** box above the key list.
  </Step>

  <Step title="Copy the token immediately">
    <Warning>
      The plaintext token is shown exactly once. After you leave the page or create another key, Armature discards the plaintext and stores only the scrypt hash. If you lose the token, you must revoke the key and create a new one.
    </Warning>

    Click **Copy** next to the token, or select the text manually, and store it in a secrets manager, environment variable, or your MCP client's configuration. Do not paste it into source control or log it.
  </Step>
</Steps>

## Using a key with the MCP endpoint

Pass the token as a standard HTTP `Authorization` header on every request to `/api/mcp`:

```http theme={null}
Authorization: Bearer amt_<key-id>_<secret>
```

For example, with `curl`:

```bash theme={null}
curl -H "Authorization: Bearer amt_abc123_xyz789..." \
     https://your-armature-host.com/api/mcp
```

Most MCP client libraries and AI agent frameworks accept an `Authorization` header configuration for HTTP transport. Consult your client's documentation for the exact configuration key.

## Key details in the dashboard

The **API keys** section lists all active keys for your organization. For each key you can see:

| Field            | Description                                                                           |
| ---------------- | ------------------------------------------------------------------------------------- |
| **Name**         | The label you gave the key at creation time.                                          |
| **Token prefix** | The `amt_<key-id>...` prefix, enough to identify the key without exposing the secret. |
| **Role**         | The organization role frozen at creation time.                                        |
| **Created**      | When the key was created.                                                             |
| **Calls**        | Total number of MCP requests authenticated with this key.                             |
| **Last used**    | Timestamp of the most recent authenticated request.                                   |

## Key scoping and roles

Each key is scoped to the organization it was created in and cannot be used across organizations. The key inherits a snapshot of your role at the moment of creation. If your role changes after you create a key, the key continues to enforce the original role until it is revoked and replaced.

<Note>
  If you need a key with a different role level — for example, a read-only viewer key for a monitoring agent — ask a workspace admin to create the key while logged in under the target role, or adjust your role first and then create the key.
</Note>

## Revoking a key

Click **Revoke** next to any key in the list and confirm the dialog. Armature deletes the scrypt hash row immediately. Any MCP client still using the revoked token will receive a `401 Unauthenticated` response on the next request.

<Warning>
  Revocation is immediate and permanent. There is no way to re-enable a revoked key. Create a new key and update the client configuration before revoking the old one to avoid downtime.
</Warning>

## Related

* [MCP API overview](/mcp-api/overview) — the full reference for Armature MCP tools, resources, and prompts.