Authentication

Olympus Cloud uses JWT (JSON Web Token) authentication. There are no API keys — all access is through short-lived JWT tokens obtained via login.

Login (Email + Password)

Public API

No authentication required for login endpoints.

POST /v1/auth/login

Request

Field	Type	Required	Description
email	string	Yes	User email address
password	string	Yes	User password
tenant_slug	string	No	Tenant identifier (auto-detected if user belongs to one tenant)
device_id	string	No	Device identifier for session tracking
device_name	string	No	Human-readable device name

Response (Success)

The login response uses a tagged status object. On success, type is "success":

{
  "status": {
    "type": "success",
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655449120",
      "tenant_id": "550e8400-e29b-41d4-a716-446655449100",
      "email": "manager@demo-restaurant.com",
      "roles": ["manager"]
    }
  }
}

Response (MFA Required)

If MFA is enabled, type is "mfa_required":

{
  "status": {
    "type": "mfa_required",
    "challenge_id": "a1b2c3d4-...",
    "challenge_code": "...",
    "factors": [
      {
        "id": "f1e2d3c4-...",
        "label": "Authenticator App",
        "factor_type": "totp",
        "enabled": true
      }
    ]
  }
}

Examples

curl

curl -X POST https://dev.api.olympuscloud.ai/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "manager@demo-restaurant.com",
    "password": "DevPassword123!"
  }'

Python

import requests

response = requests.post(
    "https://dev.api.olympuscloud.ai/v1/auth/login",
    json={
        "email": "manager@demo-restaurant.com",
        "password": "DevPassword123!",
    },
)
data = response.json()

if data["status"]["type"] == "success":
    token = data["status"]["access_token"]
    print(f"Logged in. Token: {token[:20]}...")
elif data["status"]["type"] == "mfa_required":
    print(f"MFA required. Challenge: {data['status']['challenge_id']}")

JavaScript

const response = await fetch("https://dev.api.olympuscloud.ai/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "manager@demo-restaurant.com",
    password: "DevPassword123!",
  }),
});
const data = await response.json();

if (data.status.type === "success") {
  const token = data.status.access_token;
  console.log("Logged in:", token.substring(0, 20) + "...");
}

Go

payload := map[string]string{
    "email":    "manager@demo-restaurant.com",
    "password": "DevPassword123!",
}
body, _ := json.Marshal(payload)

resp, err := http.Post(
    "https://dev.api.olympuscloud.ai/v1/auth/login",
    "application/json",
    bytes.NewBuffer(body),
)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)

status := result["status"].(map[string]interface{})
if status["type"] == "success" {
    token := status["access_token"].(string)
    fmt.Println("Token:", token[:20], "...")
}

---

Staff PIN Login

Staff at POS terminals authenticate with a PIN instead of a password. This is faster for high-throughput restaurant environments.

POST /v1/auth/staff/pin

Request

Field	Type	Required	Description
identifier	string	Yes	Staff email or username (also accepts email field name)
pin	string	Yes	6-digit PIN (also accepts code field name)
tenant_slug	string	No	Tenant identifier
location_id	string	No	Location UUID for location-scoped sessions
device_id	string	No	POS terminal device identifier

Example

curl -X POST https://dev.api.olympuscloud.ai/v1/auth/staff/pin \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "mgr01",
    "pin": "123456",
    "location_id": "550e8400-e29b-41d4-a716-446655449110"
  }'

The response format is identical to the email/password login response.

---

Register

POST /v1/auth/register

Request

Field	Type	Required	Description
tenant_slug	string	Yes	Tenant to register under
email	string	Yes	Email address
password	string	Yes	Password (minimum 8 characters)
first_name	string	No	First name
last_name	string	No	Last name
display_name	string	No	Display name

Response

{
  "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant_id": "550e8400-e29b-41d4-a716-446655449100",
  "email": "newuser@example.com",
  "email_verification_required": true
}

Example

curl -X POST https://dev.api.olympuscloud.ai/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_slug": "demo-restaurant",
    "email": "newuser@example.com",
    "password": "SecurePassword123!",
    "first_name": "Jane",
    "last_name": "Doe"
  }'

---

Token Refresh

Access tokens expire after 1 hour. Use the refresh token to get a new access token without re-authenticating.

POST /v1/auth/refresh

Request

Field	Type	Required	Description
refresh_token	string	Yes	The refresh token from login

Example

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

The response is the same format as the login response with new tokens.

---

MFA Verification

After receiving an mfa_required login response, verify with the TOTP code.

POST /v1/auth/mfa/verify

Request

Field	Type	Required	Description
challenge_id	string (UUID)	Yes	From the MFA challenge response
code	string	Yes	6-digit TOTP code from authenticator app

Example

curl -X POST https://dev.api.olympuscloud.ai/v1/auth/mfa/verify \
  -H "Content-Type: application/json" \
  -d '{
    "challenge_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "code": "123456"
  }'

On success, returns the same token response as a successful login.

---

OAuth / SSO

Initiate OAuth login with a supported provider.

GET /v1/auth/oauth/:provider

Supported providers: google, microsoft

This redirects the user to the provider's login page. After authentication, the provider redirects back to /v1/auth/oauth/:provider/callback which issues JWT tokens.

---

Session Management

GET /v1/auth/session — Get current session info

POST /v1/auth/session — Create a new session

DELETE /v1/auth/session — End current session (logout)

Example: Logout

curl -X DELETE https://dev.api.olympuscloud.ai/v1/auth/session \
  -H "Authorization: Bearer $TOKEN"

---

Using the Token

Include the JWT in all authenticated API calls:

curl https://dev.api.olympuscloud.ai/v1/commerce/orders \
  -H "Authorization: Bearer $TOKEN"

The JWT contains claims for user_id, tenant_id, roles, and location_ids, which are used by the API gateway for authorization and Row-Level Security.

---

Additional Auth Endpoints

Endpoint	Method	Description
/v1/auth/forgot-password	POST	Send password reset email
/v1/auth/reset-password	POST	Reset password with token
/v1/auth/verify-email	POST	Verify email address
/v1/auth/resend-verification	POST	Resend verification email
/v1/auth/me	GET	Get current user profile
/v1/auth/me	PUT	Update current user profile
/v1/auth/jwks	GET	Get JSON Web Key Set (public keys)
/v1/auth/locations/accessible	POST	Get locations accessible to a user
/v1/auth/staff/list	POST	List staff available for PIN login
/v1/auth/devices/check	GET	Check device trust status
/v1/auth/devices/register	POST	Register a trusted device