> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atlasent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> JWT bearer for user sessions, API keys for service-to-service.

AtlaSent supports two authentication methods. Both are fail-closed — no anonymous access.

## JWT Bearer (user sessions)

Issued by Supabase Auth. Include on every request:

```http theme={null}
GET /v1/session
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

The JWT is validated server-side on every request. Permissions derive from the caller's org role:

| Role | Permissions |
| - | - |
| `admin` | Everything. |
| `approver` | evaluate, permits, audit:read, approvals:read/resolve |
| `member` | evaluate, permits:read/consume |
| `viewer` | Read-only: audit, policies, permits. |

## API Key (service / agent auth)

Create in **Console → Settings → API Keys**. Include on every request using the `Authorization: Bearer` header:

```http theme={null}
POST /v1/evaluate
Authorization: Bearer ask_live_abc123...
Content-Type: application/json
```

API keys are stored server-side as **SHA-256 hashes**. The plaintext is never persisted; a lost key cannot be recovered — it must be rotated.

<Warning>
  The `X-AtlaSent-Key` header is deprecated and will be removed in a future
  version. Migrate all service integrations to `Authorization: Bearer <api_key>`.
</Warning>

## Scopes

API keys get a scope set at creation time. Scopes use the `resource:action`
form — bare names such as `evaluate`, `audit`, or `admin` are not valid scopes
and cannot be assigned to a key.

| Scope | What it grants |
| - | - |
| `evaluate:write` | `POST /v1/evaluate` |
| `verify:execute` | `POST /v1-verify-permit` |
| `audit:read` | Audit reads and signed audit exports |
| `approvals:read` / `approvals:write` | Reading and resolving approval requests |
| `policy:write` | Policy authoring |

<Warning>
  Give each service the narrowest scope it needs. A runtime agent typically needs only `evaluate:write` and `verify:execute`. Create separate keys for evaluation vs. audit export, so a compromise is contained.
</Warning>

## Rotating keys

To rotate an API key without service interruption:

<Steps>
  <Step title="Create a new key">
    In **Console → Settings → API Keys**, create a new key with the same scopes as the key you are rotating.
  </Step>

  <Step title="Deploy the new key">
    Update the secret your deployment reads (for example `ATLASENT_API_KEY`) to the new key and redeploy or restart the service.
  </Step>

  <Step title="Revoke the old key">
    Once the new key is confirmed working, revoke the old key in the Console.
  </Step>
</Steps>

Store API keys in a secrets manager rather than in environment files or source control.

## Fail-closed

If credentials are absent, invalid, or expired, **every endpoint returns 401**. A valid credential that lacks the scope or role an endpoint requires returns **403**, and the action does not proceed. Audit writes are atomic with evaluation — if the audit write fails, the evaluation fails.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.