Skip to main content

Authentication

The BOSS Platform API uses JWT (JSON Web Tokens) for authentication.

Authentication Flow​

Getting Started​

1. Register a new account​

curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123!",
    "name": "John Doe"
  }'

2. Login to get tokens​

curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123!"
  }'

Response:

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 3600
  }
}

3. Use access token in requests​

curl -X GET http://localhost:3000/api/v1/tickets \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Types​

Access Token​

  • Validity: 1 hour (configurable)
  • Usage: Include in Authorization: Bearer <token> header
  • Scope: All authenticated endpoints

Refresh Token​

  • Validity: 7 days (configurable)
  • Usage: Get new access token when it expires
  • Endpoint: POST /auth/refresh

Security Best Practices​

  1. Store tokens securely: Use HttpOnly cookies or secure storage
  2. Never share tokens: Treat them like passwords
  3. Refresh before expiry: Check token expiration and refresh proactively
  4. Use HTTPS: Always use secure connections in production

Error Responses​

401 Unauthorized​

{
  "success": false,
  "error": "AUTH_FAILED",
  "message": "Invalid email or password"
}

403 Forbidden​

{
  "success": false,
  "error": "INSUFFICIENT_PERMISSIONS",
  "message": "You do not have permission to perform this action"
}

Next Steps​