# EnvVault API Reference

EnvVault manages encrypted variables, passwords, API keys, browser session tokens, short-lived AI session tokens, users, and browser-extension actions.

## Authentication

Use `Authorization: Bearer <token>` or `X-API-Key: <token>` unless an endpoint lists `auth: none`.

Session tokens may be scoped to one or more applications. Scoped tokens can only access matching application data.

## Endpoints

### System

#### GET /api/v1/health

- id: `health.get`
- auth: `none`
- summary: Health check.

### Variables

#### GET /api/v1/variables/

- id: `variables.list`
- auth: `read`
- summary: List variable metadata. Values are not returned.
- query params: `application`, `environment`, `type`

#### GET /api/v1/variables/{name}

- id: `variables.get`
- auth: `read`
- summary: Retrieve one decrypted variable value.
- query params: `application`, `environment`

#### POST /api/v1/variables/

- id: `variables.create`
- auth: `write`
- summary: Create or upsert a variable.
- required body fields: `name`, `value`
- optional body fields: `application`, `environment`, `description`, `type`, `expires_at`, `metadata`

#### PATCH /api/v1/variables/{name}

- id: `variables.update`
- auth: `write`
- summary: Update value, description, type, expiry, metadata, name, application, or environment.
- query params: `application`, `environment`
- required body fields: none
- optional body fields: `value`, `description`, `type`, `expires_at`, `metadata`, `new_name`, `new_application`, `environment`

#### POST /api/v1/variables/bulk

- id: `variables.bulk`
- auth: `read`
- summary: Retrieve multiple decrypted variable values by name.
- required body fields: `names`
- optional body fields: `application`, `environment`

#### DELETE /api/v1/variables/{name}

- id: `variables.delete`
- auth: `write`
- summary: Delete one variable.
- query params: `application`, `environment`

### Applications

#### GET /api/v1/applications/

- id: `applications.list`
- auth: `read`
- summary: List applications plus APP_DESCRIPTION and GITHUB_URL metadata when present.

### Cookies

#### POST /api/v1/cookies/sync

- id: `cookies.sync`
- auth: `write`
- summary: Bulk upsert browser cookies as session_token variables for an application.
- required body fields: `application`, `cookies`
- optional body fields: none

#### GET /api/v1/cookies/{application}

- id: `cookies.get`
- auth: `read`
- summary: Get decrypted session_token cookies for an application.

#### DELETE /api/v1/cookies/{application}

- id: `cookies.delete`
- auth: `write`
- summary: Delete all session_token cookies for an application.

### Actions

#### POST /api/v1/actions/

- id: `actions.create`
- auth: `write`
- summary: Create an action for the browser extension to execute.
- required body fields: `application`, `action_type`, `payload`
- optional body fields: `expires_at`

#### GET /api/v1/actions/pending

- id: `actions.pending`
- auth: `read`
- summary: List pending extension actions.
- query params: `application`

#### GET /api/v1/actions/{id}

- id: `actions.get`
- auth: `read`
- summary: Get one extension action.

#### POST /api/v1/actions/{id}/complete

- id: `actions.complete`
- auth: `write`
- summary: Mark an action completed or failed.
- required body fields: none
- optional body fields: `success`, `result`

#### GET /api/v1/actions/

- id: `actions.list`
- auth: `read`
- summary: List actions with optional filters.
- query params: `application`, `status`, `limit`

### API Keys

#### GET /api/v1/api-keys/

- id: `api_keys.list`
- auth: `admin`
- summary: List account API keys. Application-scoped session tokens are blocked.

#### POST /api/v1/api-keys/

- id: `api_keys.create`
- auth: `admin`
- summary: Create a new API key. Raw key is shown once. Application-scoped session tokens are blocked.
- required body fields: `name`
- optional body fields: `role`

#### DELETE /api/v1/api-keys/{id}

- id: `api_keys.revoke`
- auth: `admin`
- summary: Revoke an API key. Application-scoped session tokens are blocked.

### Sessions

#### POST /api/v1/sessions/

- id: `sessions.create`
- auth: `admin`
- summary: Create or initiate creation of a short-lived session token.
- required body fields: none
- optional body fields: `ttl_seconds`, `role`, `applications`, `description`, `skip_2fa`

#### POST /api/v1/sessions/verify

- id: `sessions.verify`
- auth: `none`
- summary: Verify an emailed code and return the raw session token.
- required body fields: `verification_id`, `code`
- optional body fields: none

#### GET /api/v1/sessions/

- id: `sessions.list`
- auth: `read`
- summary: List current user's session tokens.
- query params: `include_expired`

#### DELETE /api/v1/sessions/{id}

- id: `sessions.revoke`
- auth: `read`
- summary: Revoke one session token.

#### DELETE /api/v1/sessions/all

- id: `sessions.revoke_all`
- auth: `read`
- summary: Revoke all active session tokens for the current user.

### Authentication

#### POST /api/v1/auth/login

- id: `auth.login`
- auth: `none`
- summary: Password login. Returns a web session token.
- required body fields: `username`, `password`
- optional body fields: none

#### POST /api/v1/auth/logout

- id: `auth.logout`
- auth: `read`
- summary: Revoke current web session or session token.

#### POST /api/v1/auth/change-password

- id: `auth.change_password`
- auth: `read`
- summary: Change current user's password.
- required body fields: `new_password`
- optional body fields: `current_password`

#### POST /api/v1/auth/forgot-password

- id: `auth.forgot_password`
- auth: `none`
- summary: Request a password reset code by email.
- required body fields: `email`
- optional body fields: none

#### POST /api/v1/auth/reset-password

- id: `auth.reset_password`
- auth: `none`
- summary: Reset password with email verification code.
- required body fields: `email`, `code`, `new_password`
- optional body fields: none

### Users

#### POST /api/v1/users/

- id: `users.create`
- auth: `none or site_admin`
- summary: Register a user or admin-create one.
- required body fields: `username`
- optional body fields: `email`, `password`, `default_role`, `is_admin`

#### GET /api/v1/users/me

- id: `users.me`
- auth: `read`
- summary: Get current user and current token metadata.

#### GET /api/v1/users/

- id: `users.list`
- auth: `site_admin`
- summary: List all users.

#### GET /api/v1/users/pending

- id: `users.pending`
- auth: `site_admin`
- summary: List pending user registrations.

#### POST /api/v1/users/{id}/approve

- id: `users.approve`
- auth: `site_admin`
- summary: Approve a pending user and create their first API key.
- required body fields: none
- optional body fields: `role`

#### POST /api/v1/users/{id}/reject

- id: `users.reject`
- auth: `site_admin`
- summary: Reject a pending user.

#### DELETE /api/v1/users/{id}

- id: `users.delete`
- auth: `site_admin`
- summary: Delete a user and owned data.

#### POST /api/v1/users/{id}/reset-password

- id: `users.reset_password`
- auth: `site_admin`
- summary: Send or create a password reset for a user.

### Personal API Keys

#### GET /api/v1/users/me/api-keys

- id: `users.api_keys.list`
- auth: `api_key or web_session`
- summary: List current user's API keys.

#### POST /api/v1/users/me/api-keys

- id: `users.api_keys.create`
- auth: `api_key or web_session`
- summary: Create a personal API key. Raw key is shown once.
- required body fields: none
- optional body fields: `name`, `role`

#### DELETE /api/v1/users/me/api-keys/{id}

- id: `users.api_keys.revoke`
- auth: `api_key or web_session`
- summary: Revoke one personal API key.

#### POST /api/v1/users/me/api-keys/rotate

- id: `users.api_keys.rotate`
- auth: `api_key or web_session`
- summary: Revoke current API keys and create a replacement.

### AI Setup

#### POST /api/v1/ai-setup

- id: `ai_setup.create`
- auth: `admin`
- summary: Create a one-time 10-minute AI setup link with an embedded session token.

#### GET /ai-setup/{id}

- id: `ai_setup.get`
- auth: `none`
- summary: Consume a one-time AI setup link and return Markdown setup instructions.

### SSO

#### GET /auth/login

- id: `sso.login`
- auth: `none`
- summary: Start Authentik OAuth login when SSO is configured.

#### GET /auth/callback

- id: `sso.callback`
- auth: `none`
- summary: OAuth callback for Authentik.
- query params: `code`, `state`

#### GET /auth/logout

- id: `sso.logout`
- auth: `none`
- summary: Clear local session and redirect through Authentik logout when configured.