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

# Authentication

> Register a user, log in, rotate an API key, read the current user. API keys go in the Authorization header.

Authentication lives under `/api/v1/auth/`. Every endpoint outside `/auth/register` and `/auth/login` requires `Authorization: Bearer <api-key>`.

The route file is [`app/api/routes/auth.py`](https://github.com/certior/certior/blob/main/app/api/routes/auth.py).

## `POST /auth/register`

Create a new user account and receive an API key.

**Request body** (`RegisterRequest`):

```json theme={null}
{
  "email":    "demo@example.com",
  "name":     "Demo User",
  "password": "..."
}
```

**Response** (`201 Created`, `RegisterResponse`):

```json theme={null}
{
  "id":       "...",
  "email":    "demo@example.com",
  "api_key":  "ck-..."
}
```

The `api_key` is shown once. Store it securely.

## `POST /auth/login`

Exchange credentials for an API key.

**Request body** (`LoginRequest`):

```json theme={null}
{ "email": "demo@example.com", "password": "..." }
```

**Response** (`LoginResponse`): same shape as register.

## `POST /auth/rotate`

Rotate the calling user's API key. Old key is invalidated; new one is returned.

```http theme={null}
POST /api/v1/auth/rotate
Authorization: Bearer <current-api-key>
```

**Response** (`RotateKeyResponse`):

```json theme={null}
{ "api_key": "ck-new..." }
```

## `GET /auth/me`

Return the current user.

```http theme={null}
GET /api/v1/auth/me
Authorization: Bearer <api-key>
```

**Response** (`UserResponse`):

```json theme={null}
{
  "id":    "...",
  "email": "demo@example.com",
  "name":  "Demo User",
  "role":  "VIEWER"
}
```

## Roles

The codebase recognises `ADMIN`, `OPERATOR`, `APPROVER`, `AUDITOR`, `VIEWER`, and `POLICY_AUTHOR`. Endpoints that require a specific role declare it via the `require_role(...)` dependency - see the per-endpoint docs.

## See also

* [Tasks](/api/tasks) - first endpoint that needs an API key.
* [Configuration](/reference/configuration) - the env vars that control key storage.