Aıon

Documentation

Session Auth API Reference

User registration, login, session management, password reset, OAuth, and email verification

Note on Authentication Methods

Session authentication is primarily used by the web dashboard. For API integrations, we recommend using API keys for better security and control.

Session Cookie Authentication

Most endpoints set or require an HttpOnly session cookie automatically. For API clients that cannot use cookies, you can pass the session token via the Authorization: Bearer <token> header instead.

Registration & Login

POST/api/v2/auth/session/register

Register a new user account. Creates user, tenant, and optionally a session for immediate login. Password must be 8-128 characters with at least one uppercase letter, one lowercase letter, and one digit.

Request

{
  "email": "newuser@example.com",
  "password": "SecurePassword123!",
  "name": "John Doe",
  "organization_name": "Acme Corporation",
  "auto_login": false
}

Response

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "newuser@example.com",
  "name": "John Doe",
  "tenant_id": "660e8400-e29b-41d4-a716-446655440000",
  "session_id": null,
  "session_token": null,
  "email_verification_required": true,
  "email_sent": true,
  "email_error": null,
  "message": "Registration successful"
}
POST/api/v2/auth/session/login

Login with email and password. Creates a new session and sets an HttpOnly cookie with the session token.

Request

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "remember_me": false
}

Response

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "name": "John Doe",
  "email_verified": true,
  "is_active": true,
  "session_id": "770e8400-e29b-41d4-a716-446655440000",
  "session_token": null,
  "message": "Login successful"
}
POST/api/v2/auth/session/logout

Logout and invalidate the current session. Revokes the session in the database and clears the cookie. Pass logout_all=true as a query parameter to revoke all sessions for the user.

Request

// Query parameter (optional):
// ?logout_all=true


// No request body required.
// Session cookie or Authorization header is used.

Response

{
  "message": "Logout successful"
}
GET/api/v2/auth/session/me

Get current authenticated user information. Validates the session and returns user details.

Response

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "name": "John Doe",
  "email_verified": true,
  "is_active": true,
  "created_at": "2025-01-15T10:30:00Z",
  "last_login_at": "2025-06-01T14:22:00Z"
}

Session Management

POST/api/v2/auth/session/refresh

Refresh the current session by extending its expiry. Returns updated session information.

Response

{
  "session_token": "sess_abc123...",
  "expires_at": "2025-06-08T14:22:00Z",
  "session_extended": true
}
GET/api/v2/auth/session/sessions

List all active sessions for the current user. Each session includes device information and whether it is the current session.

Response

[
  {
    "session_id": "770e8400-e29b-41d4-a716-446655440000",
    "device_name": "Web Browser (Mozilla/5.0...)",
    "ip_address": "192.168.1.100",
    "last_accessed_at": "2025-06-01T14:22:00Z",
    "created_at": "2025-05-28T09:00:00Z",
    "expires_at": "2025-06-08T09:00:00Z",
    "is_current": true
  },
  {
    "session_id": "880e8400-e29b-41d4-a716-446655440000",
    "device_name": "Web Browser (Chrome/125.0...)",
    "ip_address": "10.0.0.50",
    "last_accessed_at": "2025-05-30T11:15:00Z",
    "created_at": "2025-05-25T08:00:00Z",
    "expires_at": "2025-06-04T08:00:00Z",
    "is_current": false
  }
]
DELETE/api/v2/auth/session/sessions/{session_id}

Revoke a specific session by its ID. Use this to remotely log out another device.

Response

{
  "message": "Session revoked successfully"
}
POST/api/v2/auth/session/rotate-session

Rotate the current session token. Creates a new session with a new token and revokes the old one. Used after security-sensitive operations like password changes to prevent session fixation. The new session token is set in the HttpOnly cookie.

Response

{
  "session_id": "990e8400-e29b-41d4-a716-446655440000",
  "message": "Session rotated successfully"
}

Password Reset

POST/api/v2/auth/session/password-reset/request

Request a password reset email. Always returns a success message to prevent email enumeration.

Request

{
  "email": "user@example.com"
}

Response

{
  "message": "If the email exists, a reset link has been sent"
}
GET/api/v2/auth/session/password-reset/validate

Validate a password reset token before showing the reset form. Pass the token as a query parameter.

Request

// Query parameter:
// ?token=reset_token_from_email

Response

{
  "valid": true,
  "email": "user@example.com",
  "expires_in_minutes": 45
}
POST/api/v2/auth/session/password-reset/complete

Complete password reset with a new password. Automatically logs in the user after successful reset by setting a session cookie.

Request

{
  "token": "reset_token_from_email",
  "new_password": "NewSecurePassword123!"
}

Response

{
  "success": true,
  "message": "Password reset successful",
  "user_id": "550e8400-e29b-41d4-a716-446655440000"
}

OAuth Authentication

POST/api/v2/auth/session/google

Login or register with a Google OAuth ID token (client-side flow). Validates the Google ID token and creates a session. Supports optional password for smart account linking with existing local accounts.

Request

{
  "id_token": "google_oauth_id_token",
  "remember_me": false,
  "password": null
}

Response

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@gmail.com",
  "name": "John Doe",
  "email_verified": true,
  "is_active": true,
  "session_id": "770e8400-e29b-41d4-a716-446655440000",
  "session_token": null,
  "message": "Google login successful"
}
POST/api/v2/auth/session/google/initiate

Initiate the server-side Google OAuth flow with CSRF protection. Returns an authorization URL to redirect the user to Google. Pass the action as a query parameter: 'login', 'register', or 'link'.

Request

// Query parameter (optional):
// ?action=login

Response

{
  "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&state=...",
  "state": "csrf_state_token"
}
GET/api/v2/auth/session/google/callback

Google OAuth callback handler for the server-side authorization code flow. Called by Google after user authorizes the application. Validates the state parameter for CSRF protection, exchanges the authorization code for tokens, and creates a session.

Request

// Query parameters (set by Google redirect):
// ?code=authorization_code&state=csrf_state_token
// or on error:
// ?error=access_denied

Response

{
  "message": "OAuth login successful",
  "redirect_url": "https://app.example.com/auth/oauth-success",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@gmail.com",
    "name": "John Doe",
    "email_verified": true
  }
}
POST/api/v2/auth/session/link-provider

Link an OAuth provider to an existing authenticated account. Requires a valid session. Can optionally require password verification for extra security.

Request

{
  "provider": "google",
  "id_token": "google_oauth_id_token",
  "authorization_code": null,
  "redirect_uri": null,
  "require_password_verification": false,
  "password": null
}

Response

{
  "success": true,
  "message": "Google account linked successfully",
  "provider": "google",
  "provider_email": "user@gmail.com"
}

Email Verification

POST/api/v2/auth/session/verify-email

Verify user email with the verification token received via email.

Request

{
  "token": "email_verification_token"
}

Response

{
  "success": true,
  "message": "Email verified successfully",
  "email_verified": true
}
POST/api/v2/auth/session/resend-verification

Resend verification email to the current authenticated user. Requires a valid session but allows unverified users. No request body needed.

Response

{
  "message": "Verification email sent"
}
POST/api/v2/auth/session/resend-verification-by-email

Resend verification email by email address without requiring authentication. Returns success regardless of whether the email exists to prevent enumeration.

Request

{
  "email": "user@example.com"
}

Response

{
  "message": "If the email exists and is unverified, a verification email has been sent"
}
GET/api/v2/auth/session/email-verification-status

Check the current user's email verification status. Requires a valid session.

Response

{
  "email_verified": true,
  "email": "user@example.com"
}

Related

Authentication Guide

Complete authentication overview

API Keys Reference

Recommended for API integrations