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

# Authenticate REST API requests with an Armature API key

> Send your Armature API key as a bearer token on every REST API request. The key scopes responses to your organization and enforces the role it was issued under.

The Armature REST API uses the same API keys as the [MCP API](/mcp-api/overview). Every request includes the key as a bearer token in the `Authorization` header. The key identifies your organization, the actor (API key or user), and the role the key was created under.

## Generate a key

Create a key from the dashboard at **Settings → API keys**. The token is shown once — copy it into a secrets manager immediately. See [Create and manage API keys](/settings/api-keys) for the full flow, token format, and revocation steps.

## Send the key

Pass the token in the `Authorization` header on every request:

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

A minimal `curl` example against the org endpoint:

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

The response confirms the key, the role enforced for this request, and the organization context:

```json theme={null}
{
  "organization": {
    "id": "org_…",
    "slug": "your-org",
    "name": "Your organization"
  },
  "actor": {
    "apiKeyId": "key_…",
    "apiKeyName": "ci-runner",
    "userProfileId": null,
    "role": "editor",
    "email": null
  }
}
```

Use `GET /org` as a smoke test for any new key or environment.

## Roles and required permissions

The role frozen at API key creation time is enforced on every request. Read endpoints are open to all roles; write endpoints (create, update, archive, dispatch) require `editor`, `admin`, or `owner`.

| Surface                           | Read                              | Write                                    |
| --------------------------------- | --------------------------------- | ---------------------------------------- |
| `/org`                            | any role                          | —                                        |
| `/mcp-servers`                    | any role                          | `editor`, `admin`, `owner`               |
| `/workflows`                      | any role                          | `editor`, `admin`, `owner`               |
| `/workflows/{id}/runs` (dispatch) | —                                 | `editor`, `admin`, `owner`               |
| `/runs`                           | any role                          | —                                        |
| `/insights/*`                     | any role with the feature enabled | `editor`, `admin`, `owner` (topic edits) |

If your role does not have permission for a request, the API returns `403` with `error.code = forbidden_role`. To change a key's role, revoke it and create a new key under the desired role.

## Authentication failures

| Status                 | Cause                                                                                                                    | Fix                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| `401 unauthenticated`  | Missing, malformed, or revoked token                                                                                     | Verify the `Authorization` header and check the key list in **Settings → API keys**. |
| `403 forbidden_role`   | The key's role is too low for this operation                                                                             | Use a key created under a higher role.                                               |
| `403 feature_disabled` | The endpoint depends on a feature that is not enabled for your organization (most often MCP Analytics for `/insights/*`) | Enable the feature from the dashboard or contact your admin.                         |

## Related

* [Create and manage API keys](/settings/api-keys)
* [REST API overview](/rest-api/overview)
* [MCP API authentication](/mcp-api/authentication)