API Access

Build custom integrations using the Olympus Cloud REST API to automate workflows, sync data with other systems, and extend platform functionality.

Overview

The Olympus Cloud API provides programmatic access to:

Area	Capabilities
Workforce	Schedules, time entries, labor reports
Staff	Staff profiles and directory
Platform	Locations, tenants, roles
Analytics	Reports, metrics, exports

All API requests go through the Go API Gateway, which authenticates via JWT and proxies to the appropriate backend service.

---

Authentication

The API uses JWT Bearer tokens for authentication. There is no OAuth client_credentials flow or API key system — all access requires a valid JWT obtained by logging in.

Obtaining a Token

Authenticate with the Auth Service to receive a JWT:

curl -X POST https://api.olympuscloud.ai/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password"
  }'

Response:

{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "your-email@example.com",
    "tenant_id": "550e8400-e29b-41d4-a716-446655449100",
    "roles": ["manager"]
  }
}

Alternative Login Methods

Method	Endpoint	Use Case
Email + Password	POST /v1/auth/login	Standard login
PIN Login	POST /v1/auth/login/pin	Staff POS login
Quick Auth	POST /v1/auth/quick-login	8-digit code auth
MFA Verification	POST /v1/auth/login/mfa	Multi-factor step

Using Tokens

Include the JWT in the Authorization header on every request:

curl https://api.olympuscloud.ai/api/v1/workforce/schedules \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Protect Your Credentials

Never expose JWT tokens in client-side code, public repositories, or log files. Tokens contain tenant and role information. Compromised tokens should be invalidated by changing the user's password.

Token Refresh

JWT tokens expire after a set period. Use the refresh token to obtain a new access token:

curl -X POST https://api.olympuscloud.ai/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

---

API Endpoints

Base URL

Environment	Base URL
Production	https://api.olympuscloud.ai
Staging	https://staging.api.olympuscloud.ai
Development	https://dev.api.olympuscloud.ai

Workforce Endpoints

The workforce endpoints are available under /api/v1/workforce/ and require manager-level roles.

List Schedules

GET /api/v1/workforce/schedules?start_date=2026-01-01&end_date=2026-01-31

Returns schedules for the authenticated tenant. Requires manager, tenant_admin, or platform_admin role.

Query Parameters:

Parameter	Type	Description
start_date	string	Start date (YYYY-MM-DD)
end_date	string	End date (YYYY-MM-DD)
staff_id	UUID	Filter by specific staff member
location_id	UUID	Filter by location

List Time Entries

GET /api/v1/workforce/time-entries?start_date=2026-01-01&end_date=2026-01-15

Returns time clock entries. Managers see all entries for their tenant; staff see only their own.

Query Parameters:

Parameter	Type	Description
start_date	string	Start date (YYYY-MM-DD)
end_date	string	End date (YYYY-MM-DD)
staff_id	UUID	Filter by specific staff member

Labor Report

GET /api/v1/workforce/reports/labor?start_date=2026-01-01&end_date=2026-01-31

Returns labor cost analytics for the specified period. Requires manager privileges.

Staff Endpoints

Staff profile endpoints are available under /api/v1/staff/.

Get Staff Profile

GET /api/v1/staff/:staff_id

Returns the profile for a specific staff member. Staff can view their own profile; managers can view any profile within their tenant.

Example Response:

{
  "id": "550e8400-e29b-41d4-a716-446655449120",
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@example.com",
  "roles": ["manager"],
  "tenant_id": "550e8400-e29b-41d4-a716-446655449100",
  "location_ids": [
    "550e8400-e29b-41d4-a716-446655449110",
    "550e8400-e29b-41d4-a716-446655449111"
  ],
  "status": "active",
  "hire_date": "2024-03-15"
}

---

Access Control

All API endpoints enforce:

1. JWT Authentication — valid token required
2. Tenant Isolation — users can only access data within their tenant (Row-Level Security)
3. Role-Based Access — endpoints require specific roles (e.g., manager, tenant_admin)
4. Rate Limiting — per-tenant rate limits to prevent abuse
5. Policy Gating — the Gating Engine controls feature availability per tenant

Required Roles

Endpoint Group	Minimum Role
Workforce (schedules, time entries, labor)	manager or restaurant_manager
Staff profiles	restaurant_staff (own profile), manager (any profile)
Platform settings	tenant_admin or platform_admin

---

Rate Limits

API requests are rate-limited per tenant. When rate limited, you receive a 429 Too Many Requests response.

Rate Limit Headers

Each response includes rate limit information:

X-RateLimit-Limit: 80
X-RateLimit-Remaining: 72
X-RateLimit-Reset: 1706889600

Handling Rate Limits

Implement Backoff

When you receive a 429 response, do not retry immediately. Implement exponential backoff and respect the Retry-After header to avoid being temporarily blocked.

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry later.",
  "retry_after": 60
}

Best practices:

• Implement exponential backoff
• Cache responses when possible
• Batch operations where supported

---

Error Handling

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The staff_id parameter must be a valid UUID",
    "details": {
      "field": "staff_id",
      "reason": "invalid_format"
    }
  }
}

Common Error Codes

HTTP Status	Code	Description
400	invalid_request	Missing or invalid parameters
401	unauthorized	Invalid or expired JWT token
403	permission_denied	Insufficient role or wrong tenant
404	not_found	Resource does not exist
429	rate_limit_exceeded	Too many requests
500	internal_error	Server error (retry with backoff)

---

Webhooks

Receive real-time notifications when events occur in the platform.

Available Events

Event	Description
shift.created	New shift scheduled
shift.updated	Shift modified
time_entry.created	Clock-in or manual entry
time_entry.approved	Time entry approved

Configure Webhooks

1. Go to Settings > Integrations > Webhooks
2. Click Add Webhook
3. Enter your endpoint URL (must be HTTPS)
4. Select events to subscribe to
5. Save and copy the signing secret

Verify Webhook Signatures

Always verify webhook signatures to ensure authenticity:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

---

Support

Getting Help

When contacting support, include:

1. The request endpoint and method
2. The full error response body
3. Timestamp of the issue
4. Your tenant ID (from the JWT claims)

Contact: integrations@olympuscloud.ai

---

Related Guides

• Integrations Overview
• Platform Portal Settings
• Troubleshooting
• Getting Started