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

# Authentication

> How Enver authenticates API requests using token-based auth and Clerk sessions.

# Authentication

All Enver API endpoints require authentication. The API supports two authentication methods:

## 1. API Token (CLI & automation)

Pass your token in the `Authorization` header:

```http theme={null}
Authorization: Bearer env_live_your_token_here
```

Tokens start with `env_live_` and are scoped to specific operations. Generate them in the [dashboard](https://app.enver-os.xyz/settings/tokens).

### Scopes

| Scope           | Description                             |
| --------------- | --------------------------------------- |
| `read:secrets`  | Read encrypted payloads and shares      |
| `write:secrets` | Create, update, and delete secrets      |
| `admin`         | Full access including member management |

## 2. Clerk Session (Web dashboard)

The web dashboard authenticates using [Clerk](https://clerk.com). Session tokens are managed automatically.

***

## Token lifecycle

### Create a token

```http theme={null}
POST /api/v1/tokens
Authorization: Bearer <session-token>
Content-Type: application/json

{
  "name": "CI Pipeline",
  "scopes": ["write:secrets"],
  "ttlDays": 90
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "...",
    "name": "CI Pipeline",
    "rawToken": "env_live_...",
    "scopes": ["write:secrets"],
    "expiresAt": "2026-11-18T00:00:00.000Z"
  }
}
```

<Warning>
  The `rawToken` is only shown once. Copy and store it immediately.
</Warning>

### Token expiry

Set `ttlDays` to `null` for a non-expiring token. Expired tokens return `401 Authentication token has expired`.

### IP binding

Tokens are bound to the IP address from which they were created. Requests from a different IP return `403 Invalid IP address for this token`. See [IP Binding](/security/ip-binding) for more details.

***

## Error responses

| Status | Error                                                   | Cause                       |
| ------ | ------------------------------------------------------- | --------------------------- |
| `401`  | `Unauthorized: Missing or invalid authentication token` | No token or malformed token |
| `401`  | `Authentication token has expired`                      | Token past its TTL          |
| `403`  | `Invalid IP address for this token`                     | Request from a different IP |
| `403`  | `Forbidden: Token does not have write permissions`      | Insufficient scope          |