> For the complete documentation index, see [llms.txt](https://cerebral-systems.gitbook.io/cerebral-systems-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cerebral-systems.gitbook.io/cerebral-systems-docs/getting-started-1/authentication-and-api-keys.md).

# Authentication & API keys

Every Warrant request is authenticated with an API key. A key is scoped to one **application** (tenant) and one **role**, so a leaked key can only do what its role allows for that one application.

**Key scopes**

| Scope        | Who holds it                          | Can do                                                                            |
| ------------ | ------------------------------------- | --------------------------------------------------------------------------------- |
| **Agent**    | Your agent runtime                    | Submit action proposals (`POST /v1/actions`) and read its own actions and traces. |
| **Approver** | A human, ops bot, or approval service | Approve or reject actions that policy held for review.                            |
| **Admin**    | Operators / platform automation       | Create applications, issue and revoke keys, and read or update policy.            |

Keep the roles separated: the agent runtime should hold **only** an agent key. An agent that could approve its own held actions defeats the point of the gate, so never give an agent runtime an approver or admin key.

**Getting your first key**

When you create an application in the [dashboard](https://warrant-api-production.up.railway.app/app), signup issues one **agent key**, shown once on the welcome screen. Warrant stores only a hash of the key — it is not recoverable, so copy it immediately.

```sh
export WARRANT_URL='https://warrant-api-production.up.railway.app'
export WARRANT_API_KEY='<agent-key-shown-once>'
```

**Sending the key**

Agent and approver calls accept either header form:

```http
Authorization: Bearer <WARRANT_API_KEY>
X-Warrant-API-Key: <WARRANT_API_KEY>
```

Admin calls use a dedicated header (Bearer is also accepted on admin routes):

```http
X-Warrant-Admin-Key: <WARRANT_ADMIN_KEY>
```

Warrant derives the authoritative caller identity from the key itself. The `actor` field you send in a proposal is a claim recorded in the audit trail, not the identity used for authorization.

**Issuing and revoking keys**

In the application's **Keys** tab you can issue additional keys — pick the **agent** or **approver** scope — and revoke any key. Each new secret is shown once. A revoked key immediately stops working on its scoped endpoints.

Issue an agent key over the admin API instead:

```sh
curl -sS "$WARRANT_URL/v1/tenants/<application>/api-keys" \
  -X POST \
  -H "X-Warrant-Admin-Key: $WARRANT_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "staging-worker", "scope": "agent"}'
```

The response includes the full secret once and an `integration` bundle (endpoint map, current policy, an example proposal) that is safe to store in agent config.

**Rotating a key**

Keys have no recovery path by design. To rotate, issue a new key of the same scope, deploy it, then revoke the old one. Rotate immediately if a key is exposed in logs, a repository, or a chat transcript.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cerebral-systems.gitbook.io/cerebral-systems-docs/getting-started-1/authentication-and-api-keys.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.