Authentication

Overview

The tersOS API uses token-based authentication powered by Laravel Sanctum. Every authenticated request must include a valid API token in the Authorization header.

There are three authentication methods, each suited to different use cases:

• Bearer TokenThe primary authentication method. Used by admin dashboards, mobile apps, and third-party integrations.
• PublicNo authentication required. Used for public-facing endpoints like event listings, check-in kiosks, and day pass purchases.
• Device TokenUsed by display/signage devices. The token is passed as part of the URL path rather than in a header.

Bearer Token Authentication

Obtaining a Token

API tokens are created from the tersOS admin panel. Navigate to Settings → API Keys and generate a new token. You can assign scoped permissions to limit what each token can access.

Using the Token

Include the token in the Authorization header using the Bearer scheme:

Authorization: Bearer YOUR_API_TOKEN

Full request examples:

curl -X GET https://app.tersos.io/api/bookings \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Token Lifecycle

API tokens do not expire by default. However, you can revoke a token at any time from the admin panel. Once revoked, all requests using that token will receive a 401 Unauthorized response.

• Tokens can be created with specific permission scopes
• A token can be revoked without affecting other tokens
• If a token is compromised, revoke it immediately and generate a new one
• We recommend rotating tokens periodically as a security best practice

Public Endpoints

Certain endpoints are accessible without any authentication. These are designed for public-facing features where requiring a token would not be practical.

Public endpoints include:

• Community event listings and details
• Event registration and ticket purchasing
• Day pass purchase flows
• Public check-in and member lookup
• Event portal access

# No Authorization header needed for public endpoints
curl -X GET https://app.tersos.io/api/public/events \
  -H "Accept: application/json"

Device Token Authentication

Display and signage devices use a unique authentication method where the device token is embedded directly in the URL path. This is designed for headless devices that poll the API for state updates.

# Device token is part of the URL path
GET /api/displays/state/{device_token}
GET /api/displays/heartbeat/{device_token}

Device tokens are generated when a device is paired through the admin panel. Each device receives a unique token that identifies it within the system.

Handling Auth Errors

When authentication fails, the API returns standard HTTP error codes:

Example Error Response

{
  "success": false,
  "data": "Unauthenticated."
}

Handling Errors in Code

Always check for authentication errors and handle them gracefully:

async function apiRequest(endpoint, token) {
  const response = await fetch(`https://app.tersos.io/api${endpoint}`, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Accept': 'application/json',
    },
  });

  if (response.status === 401) {
    // Token expired or invalid — re-authenticate
    throw new Error('Authentication failed. Please refresh your token.');
  }

  if (response.status === 403) {
    // Token lacks required permissions
    throw new Error('Insufficient permissions for this endpoint.');
  }

  return response.json();
}

Next Steps