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

# Authentication API

User authentication, sessions, OAuth, and 2FA. This page lists all 23 endpoints in the Authentication area of the Visual Sentinel REST API.

Base URL: `https://visualsentinel.com`. Unless an endpoint says otherwise it accepts an API key or a session cookie, see [Authentication](https://docs.visualsentinel.com/guides/authentication.md). Most error responses use the [ErrorResponse](https://docs.visualsentinel.com/reference/models/error-response.md) shape, see [Errors](https://docs.visualsentinel.com/guides/errors.md) and [Rate limits](https://docs.visualsentinel.com/guides/rate-limits.md).

## Endpoints

- [Login](#login): `POST /api/auth/login`
- [Register new account](#register): `POST /api/auth/register`
- [Logout](#logout): `POST /api/auth/logout`
- [Get current user](#get-current-user): `GET /api/auth/me`
- [Get CSRF token](#get-csrf-token): `GET /api/auth/csrf`
- [Refresh session](#refresh-session): `POST /api/auth/refresh`
- [List active sessions](#list-sessions): `GET /api/auth/sessions`
- [Revoke session](#revoke-session): `DELETE /api/auth/sessions`
- [Enable 2FA](#enable2-fa): `POST /api/auth/2fa`
- [Confirm 2FA setup](#confirm2-fa): `PUT /api/auth/2fa`
- [Disable 2FA](#disable2-fa): `DELETE /api/auth/2fa`
- [Verify 2FA code](#verify2-fa): `POST /api/auth/2fa/verify`
- [Validate reset token](#validate-reset-token): `GET /api/auth/forgot-password`
- [Request password reset](#forgot-password): `POST /api/auth/forgot-password`
- [Reset password](#reset-password): `POST /api/auth/reset-password`
- [Update password](#update-password): `POST /api/auth/update-password`
- [Verify email (via link)](#verify-email-get): `GET /api/auth/verify-email`
- [Resend verification email](#resend-verification): `POST /api/auth/resend-verification`
- [List OAuth providers](#list-o-auth-providers): `GET /api/auth/oauth/providers`
- [Initiate Google OAuth](#google-o-auth): `GET /api/auth/oauth/google`
- [Google OAuth callback](#google-o-auth-callback): `GET /api/auth/oauth/google/callback`
- [Initiate GitHub OAuth](#github-o-auth): `GET /api/auth/oauth/github`
- [GitHub OAuth callback](#github-o-auth-callback): `GET /api/auth/oauth/github/callback`

## Login

`POST /api/auth/login`

Authenticate with email and password. Returns user data and sets session cookie.

Authentication: no session or API key needed.

Request body (required): [LoginRequest](https://docs.visualsentinel.com/reference/models/login-request.md).

**Responses**

- `200`: Login successful. Body: [AuthResponse](https://docs.visualsentinel.com/reference/models/auth-response.md).
- `401`: Invalid credentials.
- `429`: Too many login attempts.

## Register new account

`POST /api/auth/register`

Create a new user account and organization.

Authentication: no session or API key needed.

Request body (required): [RegisterRequest](https://docs.visualsentinel.com/reference/models/register-request.md).

**Responses**

- `201`: Account created. Body: [AuthResponse](https://docs.visualsentinel.com/reference/models/auth-response.md).
- `400`: Validation error.
- `409`: Email already exists.

## Logout

`POST /api/auth/logout`

End current session and clear cookies.

Authentication: session cookie only. API keys are refused.

**Responses**

- `200`: Logged out successfully.

## Get current user

`GET /api/auth/me`

Returns the currently authenticated user's profile, organization, and permissions.

Authentication: session cookie only. API keys are refused.

**Responses**

- `200`: User profile. Body: [User](https://docs.visualsentinel.com/reference/models/user.md).
- `401`: Not authenticated.

## Get CSRF token

`GET /api/auth/csrf`

Get a CSRF token for subsequent write operations. Required for session-based auth.

Authentication: session cookie only. API keys are refused.

**Responses**

- `200`: CSRF token. Body: object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `csrfToken` | string | No |   |

## Refresh session

`POST /api/auth/refresh`

Refresh the current session token to extend its lifetime.

Authentication: session cookie only. API keys are refused.

**Responses**

- `200`: Session refreshed.
- `401`: Session expired.

## List active sessions

`GET /api/auth/sessions`

Get all active sessions for the current user.

**Responses**

- `200`: Active sessions. Body: object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sessions` | array of object | No |   |

## Revoke session

`DELETE /api/auth/sessions`

Revoke a specific session by ID.

Authentication: session cookie only. API keys are refused.

**Responses**

- `200`: Session revoked.

## Enable 2FA

`POST /api/auth/2fa`

Generate a TOTP secret and QR code to enable two-factor authentication.

Authentication: session cookie only. API keys are refused.

**Responses**

- `200`: 2FA setup data. Body: object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `secret` | string | No |   |
| `qrCode` | string | No | QR code for the authenticator app, as a self-contained image data URL (data:image/svg+xml;base64,...). |
| `backupCodes` | array of string | No |   |

## Confirm 2FA setup

`PUT /api/auth/2fa`

Confirm 2FA setup by providing a valid TOTP code.

Authentication: session cookie only. API keys are refused.

Request body (required): object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | Yes | Min length 6, max length 6. |

**Responses**

- `200`: 2FA enabled.

## Disable 2FA

`DELETE /api/auth/2fa`

Disable two-factor authentication for the current user.

Authentication: session cookie only. API keys are refused.

**Responses**

- `200`: 2FA disabled.

## Verify 2FA code

`POST /api/auth/2fa/verify`

Verify a TOTP code during login when 2FA is enabled.

Authentication: no session or API key needed.

Request body (required): object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | Yes |   |
| `tempToken` | string | No |   |

**Responses**

- `200`: 2FA verified, session created.
- `401`: Invalid code.

## Validate reset token

`GET /api/auth/forgot-password`

Check if a password reset token is still valid.

Authentication: no session or API key needed.

**Parameters**

- `token` (query, string, required)

**Responses**

- `200`: Token is valid.
- `400`: Token expired or invalid.

## Request password reset

`POST /api/auth/forgot-password`

Send a password reset email to the specified address.

Authentication: no session or API key needed.

Request body (required): object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | Yes |   |

**Responses**

- `200`: Reset email sent (always returns 200 to prevent enumeration)

## Reset password

`POST /api/auth/reset-password`

Set a new password using a valid reset token.

Authentication: no session or API key needed.

Request body (required): object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | Yes |   |
| `password` | string | Yes | Min length 8. |

**Responses**

- `200`: Password reset successful.
- `400`: Invalid or expired token.

## Update password

`POST /api/auth/update-password`

Change the current user's password (requires current password).

Authentication: session cookie only. API keys are refused.

Request body (required): object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `currentPassword` | string | Yes |   |
| `newPassword` | string | Yes | Min length 8. |

**Responses**

- `200`: Password updated.
- `401`: Current password incorrect.

## Verify email (via link)

`GET /api/auth/verify-email`

Verify email address using the token from the verification email link.

Authentication: no session or API key needed.

**Parameters**

- `token` (query, string, required)

**Responses**

- `200`: Email verified.
- `400`: Invalid or expired token.

## Resend verification email

`POST /api/auth/resend-verification`

Resend the email verification link.

Authentication: session cookie only. API keys are refused.

**Responses**

- `200`: Verification email sent.

## List OAuth providers

`GET /api/auth/oauth/providers`

Get available OAuth providers (Google, GitHub).

Authentication: no session or API key needed.

**Responses**

- `200`: Available providers. Body: object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `providers` | array of object | No |   |
| `providers[].name` | string | No |   |
| `providers[].enabled` | boolean | No |   |

## Initiate Google OAuth

`GET /api/auth/oauth/google`

Redirect to Google OAuth consent screen.

Authentication: no session or API key needed.

**Responses**

- `302`: Redirect to Google.

## Google OAuth callback

`GET /api/auth/oauth/google/callback`

Handle the Google OAuth callback after user consent.

Authentication: no session or API key needed.

**Responses**

- `302`: Redirect to dashboard.

## Initiate GitHub OAuth

`GET /api/auth/oauth/github`

Redirect to GitHub OAuth consent screen.

Authentication: no session or API key needed.

**Responses**

- `302`: Redirect to GitHub.

## GitHub OAuth callback

`GET /api/auth/oauth/github/callback`

Handle the GitHub OAuth callback after user consent.

Authentication: no session or API key needed.

**Responses**

- `302`: Redirect to dashboard.

## Data models

Request and response shapes these endpoints use: [LoginRequest](https://docs.visualsentinel.com/reference/models/login-request.md), [AuthResponse](https://docs.visualsentinel.com/reference/models/auth-response.md), [RegisterRequest](https://docs.visualsentinel.com/reference/models/register-request.md), [User](https://docs.visualsentinel.com/reference/models/user.md).

Generated from the OpenAPI 3.1 specification at [https://docs.visualsentinel.com/openapi.json](https://docs.visualsentinel.com/openapi.json), the same file the interactive reference reads.