Authentication

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

Exchange a username and access code for user info and a Bearer token. This endpoint is publicly accessible (no authentication required). Request body:

{
  "username": "vigolium-admin",
  "access_code": "vgl_abc123..."
}

Success response (200):

{
  "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):

{
  "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:

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.

curl -H "Authorization: Bearer vgl_abc123..." \
     -H "X-Project-UUID: proj-uuid" \
     -H "X-User-Email: [email protected]" \
     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.

API Reference

Endpoints

Users and Roles

Current User Info

`GET /api/user/info`

Using the Token

Optional Per-Project Access Control

Disabling Authentication

​Users and Roles

​Login

​POST /api/auth/login

​Current User Info

​GET /api/user/info

​Using the Token

​Optional Per-Project Access Control

​Disabling Authentication

Users and Roles

Login

`POST /api/auth/login`

Current User Info

`GET /api/user/info`

Using the Token

Optional Per-Project Access Control

Disabling Authentication