> For the complete documentation index, see [llms.txt](https://docs.visualsentinel.com/llms.txt)

# Authentication

Endpoints accept either of two credentials unless an operation says otherwise.

## 1. Session cookie (web clients)

Call `POST /api/auth/login` with email and password to get a session cookie. The cookie is sent automatically with later requests. Session writes are CSRF protected (send `X-CSRF-Token` on POST, PUT, PATCH and DELETE).

## 2. API key (agents, integrations, scripts)

Owners and admins create keys in **Organization settings > Developer**. A key is `vs_` followed by 64 hexadecimal characters and is shown once. Send it as any of:

- `Authorization: Bearer vs_...` header (recommended)
- `X-API-Key: vs_...` header
- `?api_key=vs_...` query parameter

**API access comes with every paid plan** (Solo, Starter, Business, Agency and custom Enterprise plans). On a plan without it (Free) every key request returns 403 with code `API_ACCESS_NOT_IN_PLAN`.

Scopes have the form `{resource}:{read|write}`:

- GET requests need `{resource}:read`. POST, PUT, PATCH and DELETE need `{resource}:write`. In the dashboard, choosing write also grants read.
- `{resource}:*` grants read and write on one resource. `*` grants every resource.
- A missing scope returns 403 with code `SCOPE_DENIED` and names the scope the request needs.
- Platform admin endpoints under `/api/admin/*` are blocked for API keys whatever the scope.
- CSRF checks are skipped for API key requests.
- The role of the member who created the key applies, so a key made by a viewer cannot write.

Resources and the paths they cover:

- `monitors`: `/api/monitors/*`, `/api/monitoring/*`, `/api/metrics/*`, `/api/dependencies/*`, `/api/reports/*`, `/api/dns/*`
- `incidents`: `/api/incidents/*`
- `servers`: `/api/servers/*`
- `status-pages`: `/api/status-pages/*`
- `alerts`: `/api/alerts/*`, `/api/alert-rules/*`, `/api/alert-groups/*`
- `channels`: `/api/notification-channels/*`, `/api/notifications/*`
- `maintenance`: `/api/maintenance/*`
- `organization`: `/api/organization/*`, `/api/settings/*`, `/api/plan`, `/api/integrations/*`
- `user`: `/api/user/*`, `/api/profile/*`, `/api/onboarding/*`

Other paths, for example `/api/overview`, `/api/workspace/*`, `/api/insights/*`, `/api/analytics/*` and `/api/billing/*`, resolve to the `general` resource and need a key with the `*` scope. The dashboard does not create `*` keys.

## Session-only endpoints (cookie required)

These endpoints stay session-only by design. An API key on them returns 403 with code `SESSION_REQUIRED` (or 401 where no session exists):

- `/api/auth/*` (login, logout, refresh, 2FA, password reset, OAuth)
- `/api/billing/checkout`, `/api/billing/change-plan`, `/api/billing/portal` (billing changes)
- `DELETE /api/organization`, member and invitation management under `/api/organization/members` and `/api/organization/invitations`, `POST/PUT/DELETE /api/organization/smtp`, `POST /api/organization/leave`, and `POST/PATCH/DELETE /api/api-keys` (account and access management)
- `/api/integrations/slack/auth` (OAuth start)
- `/api/organization/invitations/accept` (email link flow)
- `/api/user/delete-account`
- `/api/user/organizations/switch` (changes the session cookie)
- `/api/chat/*`, `/api/ai/*`, `/api/incidents/{id}/summarize`, `/api/alert-groups/{id}/summarize`, `/api/reports/digest`, `POST /api/monitors/{id}/anomalies`, `POST /api/monitors/{id}/report` (AI and reporting features)

From the Visual Sentinel OpenAPI 3.1 specification at [https://docs.visualsentinel.com/openapi.json](https://docs.visualsentinel.com/openapi.json). Endpoint details are in the [API reference](https://docs.visualsentinel.com/index.md).