Authentication API

The Authentication API provides endpoints for user registration, login, logout, token management, and OAuth integration. Base Path: /api/auth/v1

Register User

POST /api/auth/v1/register

curl -X POST https://your-instance.com/api/auth/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!",
    "password_repeat": "SecurePass123!"
  }'

Request Body

string

required

User’s email address (will be normalized to lowercase)

password

string

required

User’s password (must meet password policy requirements)

password_repeat

string

required

Password confirmation (must match password)

Response

303

See Other

Success redirect to login page with confirmation message

307

Temporary Redirect

Invalid password, redirects back to registration

403

Forbidden

Password authentication is disabled

424

Failed Dependency

Failed to send verification email

If a user with the email already exists, TrailBase returns success to prevent email enumeration attacks.

Authenticate users with email and password.

POST /api/auth/v1/login

curl -X POST https://your-instance.com/api/auth/v1/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!"
  }'

Request Body

string

required

User’s email address

password

string

required

User’s password

redirect_uri

string

Optional redirect URL after successful login (for web flows)

response_type

string

Set to "code" to use Authorization Code Flow with PKCE

pkce_code_challenge

string

PKCE code challenge (required when using Authorization Code Flow)

Response (JSON)

{
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "a1b2c3d4e5f6...",
  "csrf_token": "xyz789..."
}

auth_token

string

Short-lived JWT authentication token (default: 60 minutes)

refresh_token

string

Long-lived refresh token (default: 30 days)

csrf_token

string

CSRF token for state-changing operations

For form submissions, sets auth_token and refresh_token cookies and redirects.

Authorization Code Flow with PKCE

For native/mobile apps that cannot securely store tokens:

# Step 1: Request authorization code
curl -X POST https://your-instance.com/api/auth/v1/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!",
    "response_type": "code",
    "redirect_uri": "myapp://callback",
    "pkce_code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
  }'

# Response: Redirect to myapp://callback?code=abc123...

# Step 2: Exchange code for tokens
curl -X POST https://your-instance.com/api/auth/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "authorization_code": "abc123...",
    "pkce_code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
  }'

Refresh Token

Obtain a new auth token using a refresh token.

POST /api/auth/v1/refresh

curl -X POST https://your-instance.com/api/auth/v1/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "a1b2c3d4e5f6..."
  }'

Request Body

refresh_token

string

required

Valid refresh token from login response

Response

{
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "csrf_token": "xyz789..."
}

auth_token

string

New short-lived JWT authentication token

csrf_token

string

New CSRF token

Refresh tokens are single-use. Each refresh returns a new auth token and the refresh token is rotated.

Logout

Log out the current user and delete their session(s).

Logout (GET) - All Sessions

GET /api/auth/v1/logout

curl -X GET https://your-instance.com/api/auth/v1/logout \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Cookie: auth_token=YOUR_TOKEN"

redirect_uri

string

Optional URL to redirect to after logout

Deletes all sessions for the current user and clears cookies.

Logout (POST) - Specific Session

POST /api/auth/v1/logout

curl -X POST https://your-instance.com/api/auth/v1/logout \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "a1b2c3d4e5f6..."
  }'

refresh_token

string

required

Refresh token for the specific session to delete

Deletes only the session associated with the provided refresh token. Check current authentication status.

GET /api/auth/v1/status

curl -X GET https://your-instance.com/api/auth/v1/status \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Response

{
  "user": {
    "id": "abc123",
    "email": "[email protected]",
    "email_verified": true,
    "created_at": "2026-03-01T12:00:00Z"
  },
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "csrf_token": "xyz789..."
}

Exchange Authorization Code

Exchange authorization code for auth tokens (OAuth-style flow).

POST /api/auth/v1/token

curl -X POST https://your-instance.com/api/auth/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "authorization_code": "abc123...",
    "pkce_code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
  }'

Request Body

authorization_code

string

required

Authorization code received from redirect (24 characters)

pkce_code_verifier

string

required

PKCE code verifier matching the challenge from login request

Response

{
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "a1b2c3d4e5f6...",
  "csrf_token": "xyz789..."
}

Authorization codes are single-use and expire after 5 minutes.

OAuth Integration

List OAuth Providers

Get configured OAuth providers.

GET /api/auth/v1/oauth/providers

curl -X GET https://your-instance.com/api/auth/v1/oauth/providers

Response

{
  "providers": [
    ["google", "Google"],
    ["github", "GitHub"],
    ["microsoft", "Microsoft"]
  ]
}

Initiate OAuth login flow with external provider.

GET /api/auth/v1/oauth/{provider}/login

curl -X GET "https://your-instance.com/api/auth/v1/oauth/google/login?redirect_uri=https://myapp.com/callback"

provider

string

required

OAuth provider name (google, github, microsoft, discord, etc.)

redirect_uri

string

Callback URL after successful authentication

response_type

string

Set to "code" for Authorization Code Flow

pkce_code_challenge

string

PKCE code challenge for Authorization Code Flow

Redirects to the OAuth provider’s authorization page.

OAuth Callback

Handles the callback from OAuth provider.

GET /api/auth/v1/oauth/{provider}/callback

# This is typically called by the OAuth provider, not directly

code

string

required

Authorization code from OAuth provider

state

string

required

CSRF state token for validation

Email Verification

Request Email Verification

GET /api/auth/v1/verify_email/trigger

curl -X GET https://your-instance.com/api/auth/v1/verify_email/trigger \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Verify Email

GET /api/auth/v1/verify_email/confirm/{code}

curl -X GET https://your-instance.com/api/auth/v1/verify_email/confirm/abc123xyz789

Password Management

Change Password

POST /api/auth/v1/change_password

curl -X POST https://your-instance.com/api/auth/v1/change_password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -d '{
    "old_password": "OldPass123!",
    "new_password": "NewPass456!",
    "new_password_repeat": "NewPass456!"
  }'

Request Password Reset

POST /api/auth/v1/reset_password/request

curl -X POST https://your-instance.com/api/auth/v1/reset_password/request \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

Reset Password

POST /api/auth/v1/reset_password/update

curl -X POST https://your-instance.com/api/auth/v1/reset_password/update \
  -H "Content-Type: application/json" \
  -d '{
    "reset_code": "abc123...",
    "new_password": "NewPass456!",
    "new_password_repeat": "NewPass456!"
  }'

User Management

Delete User Account

DELETE /api/auth/v1/delete

curl -X DELETE https://your-instance.com/api/auth/v1/delete \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "CSRF-Token: YOUR_CSRF_TOKEN"

Deletes the authenticated user’s account and all associated data.

Avatar Management

Get User Avatar

GET /api/auth/v1/avatar/{user_id}

curl -X GET https://your-instance.com/api/auth/v1/avatar/abc123

Returns the user’s avatar image file.

Upload Avatar

POST /api/auth/v1/avatar

curl -X POST https://your-instance.com/api/auth/v1/avatar \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -F "file=@/path/to/avatar.jpg"

Delete Avatar

DELETE /api/auth/v1/avatar

curl -X DELETE https://your-instance.com/api/auth/v1/avatar \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "CSRF-Token: YOUR_CSRF_TOKEN"

Error Responses

401

Unauthorized

Invalid credentials, expired token, or authentication required

403

Forbidden

Password authentication disabled or email not verified

409

Conflict

User already exists (only in debug mode)

429

Too Many Requests

Rate limit exceeded (password reset, email verification)

Password Policy

Password requirements can be configured via TrailBase settings. Default policy:

Minimum length: 8 characters
Must contain uppercase, lowercase, digit, and special character
Cannot be a common password

Token Lifetimes

Auth Token: 60 minutes (configurable, 2 minutes in debug mode)
Refresh Token: 30 days (configurable)
Authorization Code: 5 minutes
Email Verification Code: Varies by configuration
Password Reset Code: Varies by configuration

REST APIs

Client SDKs

CLI Reference

​Register User

​Request Body

​Response

​Login

​Request Body

​Response (JSON)

​Response (Form/Cookie)

​Authorization Code Flow with PKCE

​Refresh Token

​Request Body

​Response

​Logout

​Logout (GET) - All Sessions

​Logout (POST) - Specific Session

​Login Status

​Response

​Exchange Authorization Code

​Request Body

​Response

​OAuth Integration

​List OAuth Providers

​Response

​OAuth Login

​OAuth Callback

​Email Verification

​Request Email Verification

​Verify Email

​Password Management

​Change Password

​Request Password Reset

​Reset Password

​User Management

​Delete User Account

​Avatar Management

​Get User Avatar

​Upload Avatar

​Delete Avatar

​Error Responses

​Password Policy

​Token Lifetimes

Build docs developers (and LLMs) love

Register User

Request Body

Response

Login

Request Body

Response (JSON)

Response (Form/Cookie)

Authorization Code Flow with PKCE

Refresh Token

Request Body

Response

Logout

Logout (GET) - All Sessions

Logout (POST) - Specific Session

Login Status

Response

Exchange Authorization Code

Request Body

Response

OAuth Integration

List OAuth Providers

Response

OAuth Login

OAuth Callback

Email Verification

Request Email Verification

Verify Email

Password Management

Change Password

Request Password Reset

Reset Password

User Management

Delete User Account

Avatar Management

Get User Avatar

Upload Avatar

Delete Avatar

Error Responses

Password Policy

Token Lifetimes