Authentication & OAuth
Authentication
All authenticated endpoints require a Bearer token in the Authorization header:
1Authorization: Bearer <access_token>Access tokens are JWTs issued on login or OAuth callback. Refresh tokens can be used to obtain new access tokens without re-authenticating.
Sign Up
Create a new user account. A verification email is sent before the account can be used to log in.
1POST /api/v1/auth/signup2Content-Type: application/json34{5 "email": "user@example.com",6 "password": "securepassword123",7 "name": "John Doe",8 "username": "johndoe"9}| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address (1-255 chars, valid email) |
password | string | Yes | Password (8-128 chars) |
name | string | Yes | Display name (1-255 chars) |
username | string | No | Username (3-50 chars, generated from email if omitted) |
Response (201 Created):
1{2 "message": "Account created successfully! We've sent a verification email to user@example.com. Please verify your email before logging in.",3 "email": "user@example.com",4 "userId": "550e8400-e29b-41d4-a716-446655440000",5 "verificationRequired": true6}Status Codes:
201- Account created, verification email sent400- Invalid request data409- Email already registered
Verify Email
Verify a user's email address using the token sent to their inbox.
1POST /api/v1/auth/verify-email2Content-Type: application/json34{5 "token": "verification_token_here"6}Response (200 OK):
1{2 "message": "Email verified successfully. Your account is now fully activated.",3 "verified": true4}Status Codes:
200- Email verified400- Invalid or expired token
Resend Verification Email
Request a new verification email if the original was lost or expired.
1POST /api/v1/auth/resend-verification2Content-Type: application/json34{5 "email": "user@example.com"6}Response (200 OK):
1{2 "message": "Verification email sent. Please check your inbox."3}Status Codes:
200- Verification email sent400- User not found or email already verified
Login
Authenticate a user with email/username and password. Returns access and refresh tokens on success.
1POST /api/v1/auth/login2Content-Type: application/json34{5 "identifier": "user@example.com",6 "password": "password123",7 "mfaCode": "123456",8 "rememberMe": false9}| Field | Type | Required | Description |
|---|---|---|---|
identifier | string | Yes | Email or username (1-255 chars) |
password | string | Yes | Password (1-128 chars) |
mfaCode | string | No | TOTP code if MFA is enabled (6-8 chars) |
rememberMe | boolean | No | Extend session duration (default: false) |
Response (200 OK):
1{2 "accessToken": "eyJhbGciOiJIUzI1NiIs...",3 "refreshToken": "eyJhbGciOiJIUzI1NiIs...",4 "tokenType": "Bearer",5 "expiresAt": 1704700000,6 "sessionId": "sess_abc123",7 "user": {8 "id": "550e8400-e29b-41d4-a716-446655440000",9 "username": "johndoe",10 "email": "user@example.com",11 "displayName": "John Doe",12 "roles": ["user"],13 "mfaEnabled": false,14 "lastLoginAt": "2024-01-07T12:00:00Z"15 }16}Response (202 Accepted) -- MFA Required:
If the account has MFA enabled and no mfaCode was provided:
1{2 "mfaRequired": true,3 "mfaSessionToken": "mfa_sess_xyz789",4 "message": "Multi-factor authentication is required. Please provide your MFA code."5}Re-submit the login request with the mfaCode field to complete authentication.
Status Codes:
200- Login successful202- MFA required (provide code and retry)400- Invalid request data401- Invalid credentials, account locked, account inactive, email not verified, or invalid MFA code
Refresh Token
Exchange a valid refresh token for a new access token.
1POST /api/v1/auth/refresh2Content-Type: application/json34{5 "refreshToken": "eyJhbGciOiJIUzI1NiIs..."6}Response (200 OK):
1{2 "accessToken": "eyJhbGciOiJIUzI1NiIs...",3 "refreshToken": "eyJhbGciOiJIUzI1NiIs...",4 "tokenType": "Bearer",5 "expiresAt": 17047036006}The refreshToken field is present when token rotation is enabled; store the new refresh token and discard the old one.
Status Codes:
200- Token refreshed401- Invalid or expired refresh token
Logout
Invalidate the current session and associated tokens.
1POST /api/v1/auth/logout2Content-Type: application/json34{5 "allSessions": false6}| Field | Type | Required | Description |
|---|---|---|---|
allSessions | boolean | No | Destroy all sessions for the user (default: false) |
Response (200 OK):
1{2 "message": "Logged out successfully",3 "sessionsDestroyed": 1,4 "tokensRevoked": 25}Status Codes:
200- Logout successful401- Not authenticated
OAuth 2.0
Orcher supports OAuth 2.0 authentication with GitHub, Google, and Microsoft as identity providers. All OAuth flows use PKCE (Proof Key for Code Exchange) for security.
Initiate OAuth Flow
Start an OAuth authorization flow. The response contains the URL to redirect the user to and a PKCE code verifier the client must store.
1curl -X POST https://your-server/api/v1/auth/oauth/initiate \2 -H "Content-Type: application/json" \3 -d '{"provider": "github"}'Request Body:
1{2 "provider": "github",3 "redirectUri": "https://app.example.com/auth/callback"4}| Field | Type | Required | Description |
|---|---|---|---|
provider | string | Yes | OAuth provider (github, google, microsoft) |
redirectUri | string | No | Custom callback URL (defaults to server config) |
Response (200 OK):
1{2 "authorizationUrl": "https://github.com/login/oauth/authorize?client_id=...&state=...&code_challenge=...",3 "state": "random_state_token",4 "codeVerifier": "pkce_code_verifier_value",5 "provider": "github"6}The client must:
- Store
stateandcodeVerifiersecurely (e.g., session storage). - Redirect the user to
authorizationUrl.
Status Codes:
200- OAuth flow initiated400- Invalid provider500- OAuth service not configured
OAuth Callback
Handle the redirect from the OAuth provider. The server validates the state token, exchanges the authorization code for tokens via PKCE, fetches user info, and creates or links the account.
1GET /api/v1/auth/oauth/callback?code=AUTH_CODE&state=STATE_TOKEN| Parameter | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Authorization code from provider |
state | string | Yes | State token for CSRF verification |
error | string | No | Error code if authorization failed |
error_description | string | No | Human-readable error description |
Response (200 OK):
1{2 "accessToken": "eyJhbGciOiJIUzI1NiIs...",3 "refreshToken": "eyJhbGciOiJIUzI1NiIs...",4 "tokenType": "Bearer",5 "expiresIn": 3600,6 "user": {7 "id": "550e8400-e29b-41d4-a716-446655440000",8 "email": "user@example.com",9 "name": "John Doe",10 "isNew": true,11 "oauthProvider": "github"12 }13}Status Codes:
200- Authentication successful400- Invalid callback data or provider error401- Invalid state token or PKCE verification failed
Link OAuth Account (Protected)
Connect an OAuth provider to an existing authenticated account. The client must first call the initiate endpoint, complete the provider authorization, then submit the code and verifier here.
1curl -X POST https://your-server/api/v1/oauth/link \2 -H "Authorization: Bearer YOUR_JWT_TOKEN" \3 -H "Content-Type: application/json" \4 -d '{5 "provider": "github",6 "code": "auth_code_123",7 "state": "state_token_456",8 "codeVerifier": "verifier_789"9 }'Request Body:
1{2 "provider": "github",3 "code": "auth_code_123",4 "state": "state_token_456",5 "codeVerifier": "verifier_789"6}| Field | Type | Required | Description |
|---|---|---|---|
provider | string | Yes | OAuth provider to link |
code | string | Yes | Authorization code from provider |
state | string | Yes | State token from initiate request |
codeVerifier | string | Yes | PKCE code verifier from initiate response |
Response (200 OK):
1{2 "message": "Successfully linked github account",3 "provider": "github"4}Status Codes:
200- Account linked400- Invalid request data or account already linked to another user401- Not authenticated or invalid state token409- OAuth account already linked to a different user
Unlink OAuth Account (Protected)
Remove the connection between your account and an OAuth provider. You must have at least one other authentication method (password or another linked provider) to prevent account lockout.
1curl -X DELETE https://your-server/api/v1/oauth/unlink/github \2 -H "Authorization: Bearer YOUR_JWT_TOKEN"Path Parameters:
| Parameter | Type | Description |
|---|---|---|
provider | string | Provider to unlink (github, google, microsoft) |
Response (200 OK):
1{2 "message": "Successfully unlinked github account",3 "provider": "github"4}Status Codes:
200- Account unlinked400- Cannot unlink last authentication method401- Not authenticated404- Provider not linked to this account
List Linked OAuth Accounts (Protected)
Retrieve all OAuth providers currently linked to the authenticated user.
1curl https://your-server/api/v1/oauth/accounts \2 -H "Authorization: Bearer YOUR_JWT_TOKEN"Response (200 OK):
1{2 "providers": ["github", "google"]3}Status Codes:
200- Returns list of linked providers401- Not authenticated
Device Authorization (RFC 8628)
The device authorization flow enables authentication on CLI tools and IoT devices that cannot open a browser directly. It follows RFC 8628.
Flow overview:
- Device requests a device code and user code.
- Device displays the user code and a verification URL.
- User visits the URL in a browser and enters the code.
- User approves or denies authorization.
- Device polls the token endpoint until authorized.
Request Device Code
Generate a device code and user code pair. The device should display the userCode and verificationUri to the user.
1curl -X POST https://your-server/api/v1/auth/oauth/device/code \2 -H "Content-Type: application/json" \3 -d '{"provider": "github"}'Request Body:
1{2 "provider": "github"3}Response (200 OK):
1{2 "deviceCode": "NgAyZDgyNGQtYzYwMy00MGI2LWIzNzAtZGI2MjU0MzJhOGQ0",3 "userCode": "WDJB-MJHT",4 "verificationUri": "https://your-server/api/v1/auth/oauth/device/authorize",5 "verificationUriComplete": "https://your-server/api/v1/auth/oauth/device/authorize?userCode=WDJB-MJHT",6 "expiresIn": 900,7 "interval": 58}| Field | Type | Description |
|---|---|---|
deviceCode | string | Opaque code the device uses to poll for tokens |
userCode | string | Human-readable code the user enters (e.g., WDJB-MJHT) |
verificationUri | string | URL for the user to visit |
verificationUriComplete | string | URL with code pre-filled (for QR codes) |
expiresIn | integer | Seconds until codes expire (typically 900 = 15 minutes) |
interval | integer | Minimum seconds between poll attempts |
Status Codes:
200- Device code generated400- Invalid provider429- Rate limit exceeded
Poll for Device Token
The device polls this endpoint at the interval from the device code response. Returns the current authorization status.
1curl -X POST https://your-server/api/v1/auth/oauth/device/token \2 -H "Content-Type: application/json" \3 -d '{4 "deviceCode": "NgAyZDgyNGQtYzYwMy00MGI2LWIzNzAtZGI2MjU0MzJhOGQ0",5 "provider": "github"6 }'Request Body:
1{2 "deviceCode": "NgAyZDgyNGQtYzYwMy00MGI2LWIzNzAtZGI2MjU0MzJhOGQ0",3 "provider": "github"4}The response is a tagged union with a status field. Possible statuses:
Pending -- user has not yet authorized:
1{2 "status": "pending",3 "interval": 54}Success -- user authorized, tokens available:
1{2 "status": "success",3 "accessToken": "eyJhbGciOiJIUzI1NiIs...",4 "refreshToken": "eyJhbGciOiJIUzI1NiIs...",5 "tokenType": "Bearer",6 "expiresIn": 3600,7 "user": {8 "id": "550e8400-e29b-41d4-a716-446655440000",9 "email": "user@example.com",10 "name": "John Doe",11 "isNew": false,12 "oauthProvider": "github"13 }14}Denied -- user rejected the request:
1{2 "status": "denied"3}Expired -- device code has expired (request a new one):
1{2 "status": "expired"3}Slow Down -- polling too frequently:
1{2 "status": "slowDown",3 "interval": 104}Status Codes:
200- Returns current authorization status400- Invalid request data404- Device code not found or expired429- Polling too frequently
Get Device Authorization Page
Retrieve the device authorization page data. In production this renders an HTML form; the JSON response is shown here for API clients.
1curl "https://your-server/api/v1/auth/oauth/device/authorize?userCode=WDJB-MJHT"Query Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
userCode | string | No | Pre-fill the user code field |
Response (200 OK):
1{2 "title": "Device Authorization",3 "instructions": "Enter the code shown on your device to authorize access.",4 "userCode": "WDJB-MJHT",5 "provider": null6}Authorize Device (Protected)
Submit the device authorization decision. The user must be authenticated (logged in via browser). Called when the user enters their code and clicks approve or deny.
1curl -X POST https://your-server/api/v1/auth/oauth/device/authorize \2 -H "Content-Type: application/json" \3 -H "Authorization: Bearer YOUR_JWT_TOKEN" \4 -d '{"userCode": "WDJB-MJHT", "granted": true}'Request Body:
1{2 "userCode": "WDJB-MJHT",3 "granted": true4}| Field | Type | Required | Description |
|---|---|---|---|
userCode | string | Yes | Code displayed on the device (max 20 chars) |
granted | boolean | Yes | true to approve, false to deny |
Response (200 OK):
1{2 "message": "Device authorized successfully. You can close this window.",3 "granted": true4}Status Codes:
200- Authorization recorded400- Invalid user code format401- User not authenticated404- User code not found or expired409- Code already used
Next Steps
- API Overview -- base URL, versioning, and common headers
- Workflow Endpoints -- start and manage workflow executions
- Errors & Limits -- error response format and rate limits