Authentication Endpoints

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

string

User ID (UUID)

display_name

string

User’s display name

username

string

Username (if set)

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": "[email protected]",
  "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"
}

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

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": "[email protected]"}'

{
  "message": "Magic link sent to [email protected]"
}

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

HTTP API

CLI Commands

​Overview

​Get Available Providers

​Response

​Example

​Get Current User

​Response

​Example

​Get WebSocket Token

​Response

​Example

​Logout

​Response

​Example

​OAuth Login (GitHub)

​Query Parameters

​Example

​OAuth Callback (GitHub)

​Query Parameters

​Example

​Magic Link Request

​Request Body

​Response

​Example

​Magic Link Verify

​Query Parameters

​Example

​Device Code Flow (CLI)

​Step 1: Start Device Code Flow

​Response

​Example

​Step 2: Poll for Completion

​Request Body

​Response (Pending)

​Response (Completed)

​Response (Expired)

​Example

​Step 3: User Completes Authorization

​Request Body

​Response

​Error Responses

Build docs developers (and LLMs) love

Overview

Get Available Providers

Response

Example

Get Current User

Response

Example

Get WebSocket Token

Response

Example

Logout

Response

Example

OAuth Login (GitHub)

Query Parameters

Example

OAuth Callback (GitHub)

Query Parameters

Example

Magic Link Request

Request Body

Response

Example

Magic Link Verify

Query Parameters

Example

Device Code Flow (CLI)

Step 1: Start Device Code Flow

Response

Example

Step 2: Poll for Completion

Request Body

Response (Pending)

Response (Completed)

Response (Expired)

Example

Step 3: User Completes Authorization

Request Body

Response

Error Responses