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": "user@example.com",
    "password": "SecurePass123!",
    "password_repeat": "SecurePass123!"
  }'

Request Body

string

required

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

string

required

User’s password (must meet password policy requirements)

string

required

Password confirmation (must match password)

Response

See Other

Success redirect to login page with confirmation message

Temporary Redirect

Invalid password, redirects back to registration

Forbidden

Password authentication is disabled

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": "user@example.com",
    "password": "SecurePass123!"
  }'

Request Body

string

required

User’s email address

string

required

User’s password

string

Optional redirect URL after successful login (for web flows)

string

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

string

PKCE code challenge (required when using Authorization Code Flow)

Response (JSON)

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

string

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

string

Long-lived refresh token (default: 30 days)

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": "user@example.com",
    "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

string

required

Valid refresh token from login response

Response

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

string

New short-lived JWT authentication 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"

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..."
  }'

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": "user@example.com",
    "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

string

required

Authorization code received from redirect (24 characters)

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"

string

required

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

string

Callback URL after successful authentication

string

Set to "code" for Authorization Code Flow

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

string

required

Authorization code from OAuth provider

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": "user@example.com"
  }'

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

Unauthorized

Invalid credentials, expired token, or authentication required

Forbidden

Password authentication disabled or email not verified

Conflict

User already exists (only in debug mode)

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

Authentication API

Register User

Request Body

Response

Request Body

Response (JSON)

Authorization Code Flow with PKCE

Refresh Token

Request Body

Response

Logout

Logout (GET) - All Sessions

Logout (POST) - Specific Session

Response

Exchange Authorization Code

Request Body

Response

OAuth Integration

List OAuth Providers

Response

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

​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

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