> ## 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.

# Authenticating with the Armature MCP API

> Use Armature API keys to authenticate MCP clients. Keys are org-scoped, role-frozen at creation, and passed as Bearer tokens in the Authorization header.

The Armature MCP endpoint authenticates requests using API keys issued from your Armature organization settings. You pass the key as a Bearer token in the HTTP `Authorization` header on every request. There are no session cookies, no OAuth flows, and no per-request login steps—your MCP client sends the header automatically once the key is configured.

## Token format

```
Authorization: Bearer amt_<key-id>_<secret>
```

The `amt_` prefix identifies the token as an Armature API key. The key ID and secret are both included in the single token string you copy from the dashboard.

## Creating an API key

<Steps>
  <Step title="Open API key settings">
    Go to **Settings → API keys** in your Armature dashboard.
  </Step>

  <Step title="Create a new key">
    Click **Create API key**, give it a descriptive name, and confirm. The key is generated immediately.
  </Step>

  <Step title="Copy the token">
    Copy the full token shown on screen. Armature displays the secret portion **only once** and cannot retrieve it after creation. If you lose the token, revoke the key and create a new one.
  </Step>
</Steps>

<Note>
  Keys are scoped to your organization and frozen to the issuing user's role at creation time. If the user's role changes later, the key continues to carry the role it was created with. Choose the appropriate role for the agent's intended access level before creating the key.
</Note>

## Using the key in curl

```bash theme={null}
curl -H "Authorization: Bearer amt_<key-id>_<secret>" \
  https://your-org.armature.app/api/mcp
```

In an MCP client configuration, set the same header under `headers`:

```json theme={null}
{
  "mcpServers": {
    "armature": {
      "url": "https://your-org.armature.app/api/mcp",
      "headers": {
        "Authorization": "Bearer amt_<key-id>_<secret>"
      }
    }
  }
}
```

## Revoking a key

To revoke a key, go to **Settings → API keys**, find the key by name, and click **Revoke**. Revoking deletes the hash row immediately. Any MCP request that arrives after revocation—even one already in flight—receives a `401 unauthenticated` response.

## Keeping secrets out of tool arguments

<Warning>
  Never pass API keys, bearer tokens, passwords, cookies, or any other secrets as MCP tool arguments. Armature inspects argument names before executing any tool, and arguments whose names match secret patterns are rejected outright. Pass credentials only in the HTTP `Authorization` header, where Armature expects them.
</Warning>

This restriction exists to prevent accidental credential leakage through tool call logs, agent traces, and run artifacts. The `Authorization` header is handled at the transport layer and is never echoed into Armature's run evidence or audit records.

## Next steps

* See [Roles](/mcp-api/roles) to understand which tools and operations your key's role can access.
* Manage your keys at [Settings → API keys](/settings/api-keys).