> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/trailbaseio/trailbase/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication API

> User authentication endpoints including login, register, logout, token refresh, and OAuth flows

The Authentication API provides endpoints for user registration, login, logout, token management, and OAuth integration.

**Base Path**: `/api/auth/v1`

## Register User

Register a new user with email and password.

```bash POST /api/auth/v1/register theme={null}
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

<ParamField body="email" type="string" required>
  User's email address (will be normalized to lowercase)
</ParamField>

<ParamField body="password" type="string" required>
  User's password (must meet password policy requirements)
</ParamField>

<ParamField body="password_repeat" type="string" required>
  Password confirmation (must match password)
</ParamField>

### Response

<ResponseField name="303" type="See Other">
  Success redirect to login page with confirmation message
</ResponseField>

<ResponseField name="307" type="Temporary Redirect">
  Invalid password, redirects back to registration
</ResponseField>

<ResponseField name="403" type="Forbidden">
  Password authentication is disabled
</ResponseField>

<ResponseField name="424" type="Failed Dependency">
  Failed to send verification email
</ResponseField>

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

## Login

Authenticate users with email and password.

```bash POST /api/auth/v1/login theme={null}
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

<ParamField body="email" type="string" required>
  User's email address
</ParamField>

<ParamField body="password" type="string" required>
  User's password
</ParamField>

<ParamField body="redirect_uri" type="string">
  Optional redirect URL after successful login (for web flows)
</ParamField>

<ParamField body="response_type" type="string">
  Set to `"code"` to use Authorization Code Flow with PKCE
</ParamField>

<ParamField body="pkce_code_challenge" type="string">
  PKCE code challenge (required when using Authorization Code Flow)
</ParamField>

### Response (JSON)

```json theme={null}
{
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "a1b2c3d4e5f6...",
  "csrf_token": "xyz789..."
}
```

<ResponseField name="auth_token" type="string">
  Short-lived JWT authentication token (default: 60 minutes)
</ResponseField>

<ResponseField name="refresh_token" type="string">
  Long-lived refresh token (default: 30 days)
</ResponseField>

<ResponseField name="csrf_token" type="string">
  CSRF token for state-changing operations
</ResponseField>

### Response (Form/Cookie)

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:

```bash theme={null}
# 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.

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

### Request Body

<ParamField body="refresh_token" type="string" required>
  Valid refresh token from login response
</ParamField>

### Response

```json theme={null}
{
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "csrf_token": "xyz789..."
}
```

<ResponseField name="auth_token" type="string">
  New short-lived JWT authentication token
</ResponseField>

<ResponseField name="csrf_token" type="string">
  New CSRF token
</ResponseField>

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

## Logout

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

### Logout (GET) - All Sessions

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

<ParamField query="redirect_uri" type="string">
  Optional URL to redirect to after logout
</ParamField>

Deletes all sessions for the current user and clears cookies.

### Logout (POST) - Specific Session

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

<ParamField body="refresh_token" type="string" required>
  Refresh token for the specific session to delete
</ParamField>

Deletes only the session associated with the provided refresh token.

## Login Status

Check current authentication status.

```bash GET /api/auth/v1/status theme={null}
curl -X GET https://your-instance.com/api/auth/v1/status \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
```

### Response

```json theme={null}
{
  "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).

```bash POST /api/auth/v1/token theme={null}
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

<ParamField body="authorization_code" type="string" required>
  Authorization code received from redirect (24 characters)
</ParamField>

<ParamField body="pkce_code_verifier" type="string" required>
  PKCE code verifier matching the challenge from login request
</ParamField>

### Response

```json theme={null}
{
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "a1b2c3d4e5f6...",
  "csrf_token": "xyz789..."
}
```

<Note>
  Authorization codes are single-use and expire after 5 minutes.
</Note>

## OAuth Integration

### List OAuth Providers

Get configured OAuth providers.

```bash GET /api/auth/v1/oauth/providers theme={null}
curl -X GET https://your-instance.com/api/auth/v1/oauth/providers
```

### Response

```json theme={null}
{
  "providers": [
    ["google", "Google"],
    ["github", "GitHub"],
    ["microsoft", "Microsoft"]
  ]
}
```

### OAuth Login

Initiate OAuth login flow with external provider.

```bash GET /api/auth/v1/oauth/{provider}/login theme={null}
curl -X GET "https://your-instance.com/api/auth/v1/oauth/google/login?redirect_uri=https://myapp.com/callback"
```

<ParamField path="provider" type="string" required>
  OAuth provider name (google, github, microsoft, discord, etc.)
</ParamField>

<ParamField query="redirect_uri" type="string">
  Callback URL after successful authentication
</ParamField>

<ParamField query="response_type" type="string">
  Set to `"code"` for Authorization Code Flow
</ParamField>

<ParamField query="pkce_code_challenge" type="string">
  PKCE code challenge for Authorization Code Flow
</ParamField>

Redirects to the OAuth provider's authorization page.

### OAuth Callback

Handles the callback from OAuth provider.

```bash GET /api/auth/v1/oauth/{provider}/callback theme={null}
# This is typically called by the OAuth provider, not directly
```

<ParamField query="code" type="string" required>
  Authorization code from OAuth provider
</ParamField>

<ParamField query="state" type="string" required>
  CSRF state token for validation
</ParamField>

## Email Verification

### Request Email Verification

```bash GET /api/auth/v1/verify_email/trigger theme={null}
curl -X GET https://your-instance.com/api/auth/v1/verify_email/trigger \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
```

### Verify Email

```bash GET /api/auth/v1/verify_email/confirm/{code} theme={null}
curl -X GET https://your-instance.com/api/auth/v1/verify_email/confirm/abc123xyz789
```

## Password Management

### Change Password

```bash POST /api/auth/v1/change_password theme={null}
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

```bash POST /api/auth/v1/reset_password/request theme={null}
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

```bash POST /api/auth/v1/reset_password/update theme={null}
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

```bash DELETE /api/auth/v1/delete theme={null}
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

```bash GET /api/auth/v1/avatar/{user_id} theme={null}
curl -X GET https://your-instance.com/api/auth/v1/avatar/abc123
```

Returns the user's avatar image file.

### Upload Avatar

```bash POST /api/auth/v1/avatar theme={null}
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

```bash DELETE /api/auth/v1/avatar theme={null}
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

<ResponseField name="401" type="Unauthorized">
  Invalid credentials, expired token, or authentication required
</ResponseField>

<ResponseField name="403" type="Forbidden">
  Password authentication disabled or email not verified
</ResponseField>

<ResponseField name="409" type="Conflict">
  User already exists (only in debug mode)
</ResponseField>

<ResponseField name="429" type="Too Many Requests">
  Rate limit exceeded (password reset, email verification)
</ResponseField>

## 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