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

# Authentication

> File-based user system with Bearer token authentication, roles, login, and token usage for the Vigolium API.

Vigolium uses a file-based user system with Bearer token authentication. Each user has a unique access code that serves as their API token.

## Users and Roles

Users are defined in a JSON file (default: `~/.vigolium/users.json`). On first run, the file is auto-created from the embedded template with randomly generated access codes (prefixed `vgl_`).

Three roles control API access:

| Role       | Description                                                       |
| ---------- | ----------------------------------------------------------------- |
| `admin`    | Full access, can delete resources, update config, manage projects |
| `operator` | Can run scans, ingest traffic, and execute agent operations       |
| `viewer`   | Read-only access to records, findings, stats, and scan history    |

Default users created on bootstrap:

| Name                | Role     |
| ------------------- | -------- |
| `vigolium-admin`    | admin    |
| `vigolium-operator` | operator |
| `vigolium-analyst`  | viewer   |
| `vigolium-auditor`  | viewer   |

## Login

Exchange a username and access code for user info and a Bearer token.

### `POST /api/auth/login`

This endpoint is publicly accessible (no authentication required).

**Request body:**

```json theme={null}
{
  "username": "vigolium-admin",
  "access_code": "vgl_abc123..."
}
```

**Success response (200):**

```json theme={null}
{
  "token": "vgl_abc123...",
  "user": {
    "uuid": "d4f5e6a7-...",
    "name": "vigolium-admin",
    "email": "",
    "role": "admin"
  }
}
```

**Error responses:**

| Status | Condition                         | Body                                                              |
| ------ | --------------------------------- | ----------------------------------------------------------------- |
| 400    | Missing or malformed request body | `{"error": "username and access_code are required", "code": 400}` |
| 401    | Invalid username or access code   | `{"error": "invalid username or access code", "code": 401}`       |

## Current User Info

Retrieve the authenticated user's identity and role.

### `GET /api/user/info`

Requires a valid Bearer token.

**Success response (200):**

```json theme={null}
{
  "uuid": "d4f5e6a7-...",
  "name": "vigolium-admin",
  "email": "",
  "role": "admin"
}
```

**Error responses:**

| Status | Condition                | Body                                             |
| ------ | ------------------------ | ------------------------------------------------ |
| 401    | Missing or invalid token | `{"error": "invalid Bearer token", "code": 401}` |

## Using the Token

Include the token as a Bearer token in the `Authorization` header for all subsequent API requests:

```bash theme={null}
curl -H "Authorization: Bearer vgl_abc123..." http://localhost:9002/api/info
```

## Optional Per-Project Access Control

Projects can carry an allowlist of users that may access their data — `allowed_emails` (exact match) or `allowed_domains` (suffix match) on the project row. The server reads the `X-User-Email` request header to gate access; a missing header bypasses the check, a present-but-unauthorized email returns `403 Forbidden`.

```bash theme={null}
curl -H "Authorization: Bearer vgl_abc123..." \
     -H "X-Project-UUID: proj-uuid" \
     -H "X-User-Email: alice@example.com" \
     http://localhost:9002/api/findings
```

Setting `VIGOLIUM_PROJECT_READONLY=true` disables all mutating `vigolium project` CLI subcommands for the calling host.

## Disabling Authentication

Set `no_auth: true` in `vigolium-configs.yaml` or pass the `--no-auth` flag to the server command to disable authentication entirely. This is not recommended for production use.