Authentication

Auth API: `/api/bw/v2/auth`

Allows you to authenticate users and manage secure sessions in a Boldest platform account. It provides login, token validation, automatic token refresh, and logout capabilities using OAuth2 JWT with refresh tokens.

Endpoints

POST `/api/bw/v2/auth` - Login

Generate access and refresh tokens using username and password.

Request:

u (POST) - Username
p (POST) - Password

Response HTTP 200 - Authorized:

{
  "done": "JWT generated",
  "jwt": "eyJ...", // Legacy (same as access_token)
  "access_token": "eyJ...", // Use this for API calls
  "refresh_token": "eyJ...", // Also set in HttpOnly cookie
  "token_type": "Bearer",
  "expires_in": 900 // Seconds (15 minutes)
}

Cookie Set: bw_rtoken (HttpOnly, Secure) - Refresh token for auto-renewal

Response HTTP 401 - Unauthorized:

{
  "fail": "Unauthorized"
}

GET `/api/bw/v2/auth` - Validate Token

Return authentication status and token claims.

Headers:

Authorization: Bearer <access_token>
Or Authorization-Bearer: <access_token> (alternative)

Response HTTP 200 - Authorized:

{
  "done": "JWT verified",
  "jwt": {
    "iss": "project",
    "sub": "user@example.com",
    "aud": "api/bw/v2",
    "exp": 1234567999,
    "iat": 1234567111,
    "jti": "unique-token-id",
    "type": "access",
    "perms": ["full", "admin"],
    "lang": "en",
    "langs": ["en", "es"]
  }
}

Response HTTP 401 - Unauthorized:

{
  "fail": "Unauthorized"
}

POST `/api/bw/v2/auth/refresh` - Refresh Tokens

Exchange refresh token for new token pair. Uses HttpOnly cookie automatically.

Request: No body required (refresh token read from bw_rtoken cookie)

Response HTTP 200 - Success:

{
  "access_token": "eyJ...", // NEW access token
  "refresh_token": "eyJ...", // NEW refresh token (rotated)
  "token_type": "Bearer",
  "expires_in": 900
}

Response HTTP 401 - Invalid/Expired:

{
  "error": "invalid_grant",
  "error_description": "Invalid or expired refresh token"
}

POST `/api/bw/v2/auth/logout` - Logout

Clear session and delete refresh token cookie.

Response HTTP 200:

{
  "message": "Successfully logged out"
}

Quick Usage

JavaScript

// Login
const response = await fetch('/api/bw/v2/auth', {
  method: 'POST',
  body: new URLSearchParams({ u: 'user', p: 'pass' }),
  credentials: 'include', // Required for cookies!
});
const { access_token } = await response.json();

// API Call
await fetch('/api/bw/v2/resource/YourResource', {
  headers: { Authorization: `Bearer ${access_token}` },
  credentials: 'include',
});

// Refresh (when 401/403)
await fetch('/api/bw/v2/auth/refresh', {
  method: 'POST',
  credentials: 'include',
});

// Logout
await fetch('/api/bw/v2/auth/logout', {
  method: 'POST',
  credentials: 'include',
});

cURL

# Login
curl -X POST https://domain.com/api/bw/v2/auth \
  -d "u=user&p=pass" -c cookies.txt

# API Call
curl https://domain.com/api/bw/v2/resource/YourResource \
  -H "Authorization: Bearer <token>" -b cookies.txt

# Refresh
curl -X POST https://domain.com/api/bw/v2/auth/refresh \
  -b cookies.txt -c cookies.txt

# Logout
curl -X POST https://domain.com/api/bw/v2/auth/logout \
  -b cookies.txt

Error Handling

On 401/403 response:

Call /api/bw/v2/auth/refresh
If refresh succeeds → Retry original request
If refresh fails (401) → Redirect to login

Authentication

Auth API: /api/bw/v2/auth