Skip to main content
The Armature REST API uses the same API keys as the MCP API. 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 for the full flow, token format, and revocation steps.

​
Send the key

Pass the token in the Authorization header on every request: 
Authorization: Bearer amt_<key-id>_<secret>
A minimal curl example against the org endpoint: 
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: 
{
  "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.
SurfaceReadWrite
/organy role—
/mcp-serversany roleeditor, admin, owner
/workflowsany roleeditor, admin, owner
/workflows/{id}/runs (dispatch)—editor, admin, owner
/runsany role—
/insights/*any role with the feature enablededitor, 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

StatusCauseFix
401 unauthenticatedMissing, malformed, or revoked tokenVerify the Authorization header and check the key list in Settings → API keys.
403 forbidden_roleThe key’s role is too low for this operationUse a key created under a higher role.
403 feature_disabledThe 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.