Reference

Authentication & OAuth


Authentication

All authenticated endpoints require a Bearer token in the Authorization header:

1
Authorization: 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.

1
POST /api/v1/auth/signup
2
Content-Type: application/json
3
4
{
5
"email": "user@example.com",
6
"password": "securepassword123",
7
"name": "John Doe",
8
"username": "johndoe"
9
}
FieldTypeRequiredDescription
emailstringYesEmail address (1-255 chars, valid email)
passwordstringYesPassword (8-128 chars)
namestringYesDisplay name (1-255 chars)
usernamestringNoUsername (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": true
6
}

Status Codes:

  • 201 - Account created, verification email sent
  • 400 - Invalid request data
  • 409 - Email already registered

Verify Email

Verify a user's email address using the token sent to their inbox.

1
POST /api/v1/auth/verify-email
2
Content-Type: application/json
3
4
{
5
"token": "verification_token_here"
6
}

Response (200 OK):

1
{
2
"message": "Email verified successfully. Your account is now fully activated.",
3
"verified": true
4
}

Status Codes:

  • 200 - Email verified
  • 400 - Invalid or expired token

Resend Verification Email

Request a new verification email if the original was lost or expired.

1
POST /api/v1/auth/resend-verification
2
Content-Type: application/json
3
4
{
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 sent
  • 400 - User not found or email already verified

Login

Authenticate a user with email/username and password. Returns access and refresh tokens on success.

1
POST /api/v1/auth/login
2
Content-Type: application/json
3
4
{
5
"identifier": "user@example.com",
6
"password": "password123",
7
"mfaCode": "123456",
8
"rememberMe": false
9
}
FieldTypeRequiredDescription
identifierstringYesEmail or username (1-255 chars)
passwordstringYesPassword (1-128 chars)
mfaCodestringNoTOTP code if MFA is enabled (6-8 chars)
rememberMebooleanNoExtend 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 successful
  • 202 - MFA required (provide code and retry)
  • 400 - Invalid request data
  • 401 - 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.

1
POST /api/v1/auth/refresh
2
Content-Type: application/json
3
4
{
5
"refreshToken": "eyJhbGciOiJIUzI1NiIs..."
6
}

Response (200 OK):

1
{
2
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
3
"refreshToken": "eyJhbGciOiJIUzI1NiIs...",
4
"tokenType": "Bearer",
5
"expiresAt": 1704703600
6
}

The refreshToken field is present when token rotation is enabled; store the new refresh token and discard the old one.

Status Codes:

  • 200 - Token refreshed
  • 401 - Invalid or expired refresh token

Logout

Invalidate the current session and associated tokens.

1
POST /api/v1/auth/logout
2
Content-Type: application/json
3
4
{
5
"allSessions": false
6
}
FieldTypeRequiredDescription
allSessionsbooleanNoDestroy all sessions for the user (default: false)

Response (200 OK):

1
{
2
"message": "Logged out successfully",
3
"sessionsDestroyed": 1,
4
"tokensRevoked": 2
5
}

Status Codes:

  • 200 - Logout successful
  • 401 - 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.

1
curl -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
}
FieldTypeRequiredDescription
providerstringYesOAuth provider (github, google, microsoft)
redirectUristringNoCustom 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:

  1. Store state and codeVerifier securely (e.g., session storage).
  2. Redirect the user to authorizationUrl.

Status Codes:

  • 200 - OAuth flow initiated
  • 400 - Invalid provider
  • 500 - 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.

1
GET /api/v1/auth/oauth/callback?code=AUTH_CODE&state=STATE_TOKEN
ParameterTypeRequiredDescription
codestringYesAuthorization code from provider
statestringYesState token for CSRF verification
errorstringNoError code if authorization failed
error_descriptionstringNoHuman-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 successful
  • 400 - Invalid callback data or provider error
  • 401 - Invalid state token or PKCE verification failed

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.

1
curl -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
}
FieldTypeRequiredDescription
providerstringYesOAuth provider to link
codestringYesAuthorization code from provider
statestringYesState token from initiate request
codeVerifierstringYesPKCE code verifier from initiate response

Response (200 OK):

1
{
2
"message": "Successfully linked github account",
3
"provider": "github"
4
}

Status Codes:

  • 200 - Account linked
  • 400 - Invalid request data or account already linked to another user
  • 401 - Not authenticated or invalid state token
  • 409 - OAuth account already linked to a different user

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.

1
curl -X DELETE https://your-server/api/v1/oauth/unlink/github \
2
-H "Authorization: Bearer YOUR_JWT_TOKEN"

Path Parameters:

ParameterTypeDescription
providerstringProvider to unlink (github, google, microsoft)

Response (200 OK):

1
{
2
"message": "Successfully unlinked github account",
3
"provider": "github"
4
}

Status Codes:

  • 200 - Account unlinked
  • 400 - Cannot unlink last authentication method
  • 401 - Not authenticated
  • 404 - Provider not linked to this account

List Linked OAuth Accounts (Protected)

Retrieve all OAuth providers currently linked to the authenticated user.

1
curl 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 providers
  • 401 - 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:

  1. Device requests a device code and user code.
  2. Device displays the user code and a verification URL.
  3. User visits the URL in a browser and enters the code.
  4. User approves or denies authorization.
  5. 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.

1
curl -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": 5
8
}
FieldTypeDescription
deviceCodestringOpaque code the device uses to poll for tokens
userCodestringHuman-readable code the user enters (e.g., WDJB-MJHT)
verificationUristringURL for the user to visit
verificationUriCompletestringURL with code pre-filled (for QR codes)
expiresInintegerSeconds until codes expire (typically 900 = 15 minutes)
intervalintegerMinimum seconds between poll attempts

Status Codes:

  • 200 - Device code generated
  • 400 - Invalid provider
  • 429 - 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.

1
curl -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": 5
4
}

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": 10
4
}

Status Codes:

  • 200 - Returns current authorization status
  • 400 - Invalid request data
  • 404 - Device code not found or expired
  • 429 - 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.

1
curl "https://your-server/api/v1/auth/oauth/device/authorize?userCode=WDJB-MJHT"

Query Parameters:

ParameterTypeRequiredDescription
userCodestringNoPre-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": null
6
}

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.

1
curl -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": true
4
}
FieldTypeRequiredDescription
userCodestringYesCode displayed on the device (max 20 chars)
grantedbooleanYestrue to approve, false to deny

Response (200 OK):

1
{
2
"message": "Device authorized successfully. You can close this window.",
3
"granted": true
4
}

Status Codes:

  • 200 - Authorization recorded
  • 400 - Invalid user code format
  • 401 - User not authenticated
  • 404 - User code not found or expired
  • 409 - Code already used

Next Steps