Authentication Endpoints

OAuth, magic links, device code flow, and session management

Overview

Loom supports multiple authentication flows:

• OAuth 2.0: GitHub, Google, and Okta (enterprise)
• Magic Links: Passwordless email authentication
• Device Code Flow: CLI and VS Code authentication
• Session Cookies: Web browser sessions
• API Keys: Programmatic access with scoped permissions

Get Available Providers

GET /auth/providers

Returns the list of authentication providers configured on the server.

Response

providers · string[]

Array of provider names (e.g., ["github", "google", "magic_link"])

Example

curl https://loom.ghuntley.com/auth/providers

{
  "providers": ["github", "google", "okta", "magic_link"]
}

Get Current User

GET /auth/me

Returns the currently authenticated user’s information. Requires valid session cookie or API key.

Response

id · string

User ID (UUID)

display_name · string

User’s display name

username · string

Username (if set)

email · string

Primary email address

avatar_url · string

Profile avatar URL

locale · string

Preferred locale (e.g., "en", "es", "ar")

global_roles · string[]

Array of global role names (e.g., ["system_admin", "support"])

created_at · string

ISO 8601 timestamp of account creation

Example

curl -H "Authorization: Bearer loom_sk_..." \
  https://loom.ghuntley.com/auth/me

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "display_name": "Alice Johnson",
  "username": "alice",
  "email": "[e-mail]",
  "avatar_url": "https://avatars.githubusercontent.com/u/12345",
  "locale": "en",
  "global_roles": ["user"],
  "created_at": "2025-01-15T08:30:00Z"
}

Get WebSocket Token

GET /auth/ws-token

Returns a short-lived token for WebSocket authentication. Required because HttpOnly cookies cannot be accessed by JavaScript.

Response

token · string

WebSocket token (prefix: ws_). Valid for 30 seconds, single-use.

expires_in · integer

Token lifetime in seconds (30)

Example

curl -H "Cookie: loom_session=..." \
  https://loom.ghuntley.com/auth/ws-token

{
  "token": "ws_a1b2c3d4e5f6...",
  "expires_in": 30
}

Usage: Send token in WebSocket first message:

{"type": "auth", "token": "ws_a1b2c3d4e5f6..."}

Logout

POST /auth/logout

Invalidates the current session and clears the session cookie.

Response

message · string

Success message

Example

curl -X POST -H "Cookie: loom_session=..." \
  https://loom.ghuntley.com/auth/logout

{
  "message": "Logged out successfully"
}

OAuth Login (GitHub)

GET /auth/login/github

Initiates GitHub OAuth flow. Redirects to GitHub for authorization.

Query Parameters

redirect_uri · string

URL to redirect after successful login (default: /)

Example

curl -L https://loom.ghuntley.com/auth/login/github?redirect_uri=/dashboard

User is redirected to GitHub, then back to /auth/callback/github after authorization.

OAuth Callback (GitHub)

GET /auth/callback/github

Handles OAuth callback from GitHub. Sets session cookie and redirects to redirect_uri.

Query Parameters

code · string · required

OAuth authorization code from GitHub

state · string · required

CSRF token from initial login request

error · string

Error code if authorization failed

error_description · string

Human-readable error description

Example

GET /auth/callback/github?code=abc123&state=xyz789

Sets loom_session cookie and redirects to original redirect_uri.

Magic Link Request

POST /auth/magic-link

Sends a passwordless login link to the user’s email address.

Request Body

email · string · required

Email address to send magic link to

Response

message · string

Success message

Example

curl -X POST https://loom.ghuntley.com/auth/magic-link \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]"}'

{
  "message": "Magic link sent to [e-mail]"
}

The email contains a link: https://loom.ghuntley.com/auth/magic-link/verify?token=...

Magic Link Verify

GET /auth/magic-link/verify

Verifies the magic link token and creates a session.

Query Parameters

token · string · required

Magic link token from email

redirect_uri · string

URL to redirect after login (default: /)

Example

GET /auth/magic-link/verify?token=abc123xyz789&redirect_uri=/dashboard

Sets loom_session cookie and redirects to /dashboard.

Device Code Flow (CLI)

The device code flow enables CLI and VS Code authentication without opening a browser on the same machine.

Step 1: Start Device Code Flow

POST /auth/device/start

Initiates device code flow and returns a user code and verification URL.

Response

device_code · string

Device code for polling (opaque token)

user_code · string

Short code to display to user (e.g., "ABCD-1234")

verification_url · string

URL where user enters the code (e.g., "https://loom.ghuntley.com/device")

expires_in · integer

Expiry time in seconds (default: 600)

Example

curl -X POST https://loom.ghuntley.com/auth/device/start

{
  "device_code": "opaque_device_token_abc123",
  "user_code": "ABCD-1234",
  "verification_url": "https://loom.ghuntley.com/device",
  "expires_in": 600
}

Step 2: Poll for Completion

POST /auth/device/poll

Polls for user authorization. Returns pending until user completes authorization.

Request Body

device_code · string · required

Device code from /auth/device/start

Response (Pending)

{
  "status": "pending"
}

Response (Completed)

{
  "status": "completed",
  "access_token": "loom_sk_..."
}

Response (Expired)

{
  "status": "expired"
}

Example

curl -X POST https://loom.ghuntley.com/auth/device/poll \
  -H "Content-Type: application/json" \
  -d '{"device_code": "opaque_device_token_abc123"}'

Poll every 5 seconds until status is completed or expired.

Step 3: User Completes Authorization

User visits https://loom.ghuntley.com/device, enters the user code, and authorizes:

POST /auth/device/complete

Request Body

user_code · string · required

User code displayed by CLI (e.g., "ABCD-1234")

Response

{
  "message": "Device authorized successfully"
}

Error Responses

All auth endpoints return errors in this format:

{
  "error": "invalid_token",
  "message": "Magic link token is invalid or expired"
}

Common error codes:

• unauthorized: Authentication required
• invalid_token: Token is invalid or expired
• provider_not_configured: OAuth provider not enabled
• email_send_failed: Failed to send magic link email