Authentication

Every request is authenticated with a workspace API key, sent as a bearer token:

Authorization: Bearer maetra_xxxxxxxxxxxxxxxxxxxx

Keys start with maetra_. A key belongs to one workspace and carries a fixed set of scopes. The same key authenticates the REST API and the MCP server.

Create an API key (in the dashboard)#

Open the Maetra dashboard and go to Settings → API keys.
Click Create API key.
Fill in the dialog:
- Key name — a label to recognise it later, e.g. Production FinanceAgent.
- Access scopes — choose Full access, or Custom scopes to pick per module (Discover, Comply, Govern, Secure, Audit, Task Guard). Grant the least a key needs — see Scopes below.
- IP restrictions (optional) — one or more IPs/CIDR ranges the key may be used from, e.g. 192.168.1.0/24.
Click Create. The full key is shown once — hit Copy key, store it in a secret manager, then I've saved my key.

Important Maetra stores only a hash of the key and can never show it again. If a key is lost or leaked, revoke it and create a new one — you can't recover it.

Scopes#

Scopes are checked per request. A call returns 403 Forbidden if the key is valid but lacks the required scope.

Scope	Grants
`govern:checkpoints:write`	Create checkpoints
`govern:checkpoints:read`	Read / long-poll checkpoints
`govern:policies:read`	List active policies
`secure:scan:write`	Scan content
`secure:rules:read`	List Secure rules
`secure:rules:write`	Create and update Secure rules
`secure:incidents:read`	List incidents
`discover:agents:read`	List registered agents
`task_guard:tasks:write`	Start, update, pause, resume, cancel, and complete Task Guard tasks
`task_guard:tasks:read`	Retrieve active Task Guard task context
`task_guard:checks:write`	Check action alignment and explain task relationships
`task_guard:effects:write`	Report and compare actual action effects
`task_guard:confirmations:write`	Submit trusted host user events and scope confirmations

Wildcards

A key may hold wildcard scopes: * (everything), or a module prefix like govern:* / secure:* / discover:* / task_guard:*. The dashboard's Full access grants *; picking a whole module under Custom scopes grants that module's *.

Note task_guard:confirmations:write is necessary but not sufficient for trusted host events and inline scope confirmations. The API key must also be marked as a trusted Task Guard confirmation credential for the workspace.

Check a key#

Use GET /v1/ping to confirm a key is valid and see its scopes:

curl "https://api.maetra.io/v1/ping" \
  -H "Authorization: Bearer $MAETRA_API_KEY"

{ "ok": true, "workspace_id": "ws_3Nf9k2", "scopes": ["govern:checkpoints:write"] }

Revoke a key#

Revoke a key from Settings → API keys (the row's actions menu). Revocation is immediate — further requests return 401 Unauthorized. Revoking one key never affects the others.

See Errors & rate limits for the full error format.