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. Most error responses use the ErrorResponse shape, see Errors and Rate limits.
Endpoints
- Login:
POST /api/auth/login - Register new account:
POST /api/auth/register - Logout:
POST /api/auth/logout - Get current user:
GET /api/auth/me - Get CSRF token:
GET /api/auth/csrf - Refresh session:
POST /api/auth/refresh - List active sessions:
GET /api/auth/sessions - Revoke session:
DELETE /api/auth/sessions - Enable 2FA:
POST /api/auth/2fa - Confirm 2FA setup:
PUT /api/auth/2fa - Disable 2FA:
DELETE /api/auth/2fa - Verify 2FA code:
POST /api/auth/2fa/verify - Validate reset token:
GET /api/auth/forgot-password - Request password reset:
POST /api/auth/forgot-password - Reset password:
POST /api/auth/reset-password - Update password:
POST /api/auth/update-password - Verify email (via link):
GET /api/auth/verify-email - Resend verification email:
POST /api/auth/resend-verification - List OAuth providers:
GET /api/auth/oauth/providers - Initiate Google OAuth:
GET /api/auth/oauth/google - Google OAuth callback:
GET /api/auth/oauth/google/callback - Initiate GitHub OAuth:
GET /api/auth/oauth/github - GitHub OAuth 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.
Responses
200: Login successful. Body: AuthResponse.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.
Responses
201: Account created. Body: AuthResponse.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.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, AuthResponse, RegisterRequest, User.
Generated from the OpenAPI 3.1 specification at https://docs.visualsentinel.com/openapi.json, the same file the interactive reference reads.