Authorization Overview

The ESFA Backend API uses Bearer token authentication to secure all endpoints. This document explains how authentication and authorization work within the API ecosystem.

Authentication Architecture

The ESFA system uses a two-service authentication architecture:

Authentication Service: Issues Bearer tokens (separate service)
Backend API: Validates tokens and processes requests

┌─────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client    │───▶│ Auth Service    │───▶│ Backend API     │
│             │    │ (Token Issuer)  │    │ (Token Validator)│
└─────────────┘    └─────────────────┘    └─────────────────┘

Authorization Header Format

All protected Backend API requests must include the Authorization header:

Authorization: Bearer <your-jwt-token>

Example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Characteristics

Token Format

Type: JWT (JSON Web Token)
Algorithm: As specified by the Authentication Service
Encoding: Base64-encoded JWT format

Token Lifecycle

Lifetime: Short-lived (typically minutes to hours)
Refresh: Obtain new tokens when expired
Scope: Valid for all Backend API endpoints

Token Claims

Tokens contain claims that identify:

Client application
Expiration time
Issued at time
Token issuer

Security Requirements

Transmission Security

HTTPS Only: Always use HTTPS in production
Header Security: Never log or expose tokens
Storage: Store tokens securely (memory preferred over disk)

Token Handling

Validation: Backend validates every token on each request
Expiration: Tokens expire automatically for security
Revocation: Tokens cannot be revoked once issued (rely on expiration)

Authentication Flow

1. Initial Authentication

# Request token from Authentication Service
curl -X POST https://auth.your-service.tld/v1/oauth/token/machine \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your-api-key",
    "secretKey": "your-secret-key"
  }'

Response:

{
  "data": {
    "token": "eyJhbGciOi...",
    "expires": "2025-09-05T13:31:23.174Z"
  }
}

2. API Request with Token

# Use token for Backend API calls
curl -H "Authorization: Bearer eyJhbGciOi..." \
  https://api.your-service.tld/api/v1/games/TTT/matches/match-id

3. Token Refresh (when expired)

# Get new token when current one expires
curl -X POST https://auth.your-service.tld/v1/oauth/token/machine \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your-api-key",
    "secretKey": "your-secret-key"
  }'

Response Codes

Authentication Success

200 OK: Request processed successfully with valid token

Authentication Failures

401 Unauthorized

The request lacks valid authentication credentials.

Common causes:

Missing Authorization header
Invalid token format
Expired token
Invalid/corrupted token

Example Response:

{
  "errors": [
    {
      "i18N": "UNAUTHORIZED",
      "error": "Invalid or missing authentication token",
      "type": "Unauthorized"
    }
  ]
}

Solutions:

Verify Authorization header is present
Check token format (must be Bearer <token>)
Obtain fresh token if expired
Validate token is not corrupted

403 Forbidden

Valid authentication but insufficient permissions (if applicable).

Best Practices

Token Management

class TokenManager {
  constructor(apiKey, secretKey, authServiceUrl) {
    this.apiKey = apiKey;
    this.secretKey = secretKey;
    this.authServiceUrl = authServiceUrl;
    this.token = null;
    this.expiresAt = null;
  }

  async getValidToken() {
    if (this.token && this.expiresAt && new Date() < this.expiresAt) {
      return this.token;
    }
    
    return await this.refreshToken();
  }

  async refreshToken() {
    const response = await fetch(`${this.authServiceUrl}/v1/oauth/token/machine`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        apiKey: this.apiKey,
        secretKey: this.secretKey
      })
    });

    if (!response.ok) {
      throw new Error(`Authentication failed: ${response.status}`);
    }

    const data = await response.json();
    this.token = data.data.token;
    this.expiresAt = new Date(data.data.expires);
    
    return this.token;
  }
}

Error Handling

async function makeAuthenticatedRequest(url, options = {}) {
  const token = await tokenManager.getValidToken();
  
  const response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      'Authorization': `Bearer ${token}`
    }
  });

  if (response.status === 401) {
    // Token expired, refresh and retry once
    const newToken = await tokenManager.refreshToken();
    return fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${newToken}`
      }
    });
  }

  return response;
}

Security Guidelines

Do's

✅ Always use HTTPS in production
✅ Store tokens in memory when possible
✅ Implement automatic token refresh
✅ Handle 401 errors gracefully
✅ Validate token expiration before requests

Don'ts

❌ Log or expose Bearer tokens
❌ Store tokens in client-side storage (browsers)
❌ Use HTTP for token transmission
❌ Hardcode tokens in source code
❌ Ignore token expiration

Troubleshooting

Common Issues

Issue: "Invalid or missing authentication token"

Cause: Missing or malformed Authorization header
Solution: Verify header format: Authorization: Bearer <token>

Issue: Token expires frequently

Cause: Short token lifetime
Solution: Implement proactive token refresh before expiration

Issue: Authentication works in development but fails in production

Cause: HTTP vs HTTPS configuration
Solution: Ensure all production traffic uses HTTPS

Debugging Tips

Check Token Format: Ensure JWT structure (header.payload.signature)
Verify Expiration: Check token expiration claim
Network Inspection: Use browser dev tools or network monitoring
Service Status: Verify Authentication Service availability

Authentication Machine Token: Detailed token request process
Usage Flow: Complete API workflow with examples
Error Handling: Comprehensive error response guide
Troubleshooting: Common issues and solutions

05 September 2025