Gateway Documentation

This documents the API gateway architecture and behavior. These are not callable endpoints — they describe how the gateway processes requests.

API Gateway Authentication

Comprehensive guide to the authentication and authorization middleware stack in the Olympus Cloud API Gateway.

Multi-Layered Security

The API Gateway implements six layers of authentication and authorization. All requests pass through this middleware chain before reaching backend services.

Overview

The API Gateway implements a multi-layered authentication system:

Layer	Middleware	Purpose
1	API Key Validation	Service-to-service and integration authentication
2	JWT Validation	User session authentication
3	RBAC Enforcement	Role-based access control
4	Shell Access Control	Flutter shell-specific authorization
5	Continuous Auth	Zero Trust session validation
6	Microsegmentation	Network segment isolation

API Key Authentication

Server-to-server and integration partner authentication using API keys.

Headers

X-API-Key: your-api-key-here

Or via query parameter (fallback):

GET /api/v1/endpoint?api_key=your-api-key-here

Exempt Paths

The following paths do not require API key authentication:

Path Pattern	Description
`/health`, `/healthz`	Health check endpoints
`/metrics`	Prometheus metrics
`/ws/*`	WebSocket connections
`/v1/auth/*`	Authentication endpoints
`/api/v1/public/*`	Public API endpoints
`/v1/restaurant/*`	Public restaurant data
`/v1/webhooks/*`	Webhook receivers

Response Codes

Status	Code	Description
401	`UNAUTHORIZED`	API key header missing
403	`FORBIDDEN`	API key invalid or revoked

Example Error Response

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "API key is required to access this resource.",
  "request_id": "req-abc123",
  "timestamp": "2026-01-19T14:30:00Z"
}

JWT Authentication

User session authentication via Bearer tokens.

Token Format

Access tokens are RS256-signed JWTs with standard claims:

{
  "sub": "user_abc123",
  "tenant_id": "tenant_xyz",
  "location_id": "loc_123",
  "roles": ["manager", "staff"],
  "allowed_shells": ["staff", "platform"],
  "current_shell": "staff",
  "permissions": ["orders:read", "orders:write"],
  "session_id": "sess_123",
  "iat": 1704067200,
  "exp": 1704070800,
  "iss": "olympus-auth",
  "aud": "olympus-api"
}

Authorization Header

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Context Extraction

The middleware extracts claims and sets context values:

Context Key	Source	Description
`user_id`	`sub` claim	Authenticated user ID
`tenant_id`	`tenant_id` claim	Tenant/organization ID
`location_id`	`location_id` claim	Restaurant/location ID
`roles`	`roles` claim	User role assignments
`allowed_shells`	`allowed_shells` claim	Authorized Flutter shells
`current_shell`	`X-Shell` header or claim	Active shell for session
`auth_token`	Bearer token	Raw JWT for downstream services

Token Validation

The Gateway validates:

Signature - RS256 verification with public key
Expiration - exp claim must be in future
Issuer - iss must match configured issuer
Audience - aud must match API audience

Role-Based Access Control (RBAC)

Endpoint-level access control based on user roles.

Predefined Roles

Role	Description	Typical Permissions
`super_admin`	NebusAI platform administrator	Full system access
`tenant_admin`	Tenant/organization owner	Full tenant access
`manager`	Location/restaurant manager	Location management
`staff`	Regular staff member	Operational access
`customer`	End customer	Consumer features
`kiosk`	Kiosk device identity	Self-service ordering
`api_client`	Integration partner	API-only access

Enforcement Patterns

Single Role Requirement

// Route requires exactly one specific role
RequireRole("manager")

Response if unauthorized:

{
  "error": "Forbidden",
  "code": "FORBIDDEN",
  "message": "Insufficient permissions. Required role: manager",
  "required_role": "manager",
  "request_id": "req-abc123"
}

Any Role Requirement

// Route requires at least one of the specified roles
RequireAnyRole("manager", "tenant_admin", "super_admin")

Response if unauthorized:

{
  "error": "Forbidden",
  "code": "FORBIDDEN",
  "message": "Insufficient permissions. Required one of: manager, tenant_admin, super_admin",
  "required_roles": ["manager", "tenant_admin", "super_admin"],
  "request_id": "req-abc123"
}

Ownership or Role

// Allow if user owns the resource OR has admin role
RequireOwnershipOrRole("tenant_admin")

This pattern allows:

Resource owner (user_id matches resource owner)
Admin override (user has specified admin role)

Shell-Based Access Control

Authorization based on Flutter application shell context.

Supported Shells

Shell ID	Application	Target Users
`staff`	Restaurant Staff Shell	Servers, hosts, bartenders
`customer`	Customer Shell	Restaurant guests
`kiosk`	Kiosk Shell	Self-service ordering
`kds`	Kitchen Display	Kitchen staff
`platform`	Platform Portal	Business owners
`admin`	Platform Admin	Tenant administrators
`cockpit`	Cockpit Shell	NebusAI operations
`drive_thru`	Drive-Thru Shell	Drive-thru operators
`signage`	Digital Signage	Menu boards
`workforce`	Workforce Shell	Employee management
`creator_admin`	Creator Studio	AI persona builders
`audience`	Audience Shell	Fan engagement

Shell Header

Clients must send the active shell:

X-Shell: staff

Or via the App Experience header:

X-App-Experience: restaurant-staff

Shell Validation

The middleware validates:

Allowed Shells - User's allowed_shells JWT claim
Current Shell - Must be in allowed list
Route Access - Shell must have permission for endpoint

Shell-to-Route Mapping

staff:
  - /api/v1/orders/*
  - /api/v1/tables/*
  - /api/v1/payments/*

customer:
  - /api/v1/menu/*
  - /api/v1/orders/self/*
  - /api/v1/loyalty/*

kiosk:
  - /api/v1/menu/*
  - /api/v1/orders/kiosk/*
  - /api/v1/payments/kiosk/*

platform:
  - /api/v1/analytics/*
  - /api/v1/reports/*
  - /api/v1/settings/*

Zero Trust Continuous Authentication

Ongoing session validation beyond initial authentication.

Configuration

continuous_auth:
  enabled: true
  base_reverification_interval: 30m
  min_reverification_interval: 5m
  max_reverification_interval: 4h
  max_session_age: 24h
  risk_score_threshold_for_mfa: 0.6
  terminate_on_high_risk: true
  high_risk_termination_threshold: 0.95

Risk Scoring Factors

Factor	Weight	Description
IP Change	0.3	Different IP from session start
Device Change	0.4	Different device fingerprint
Location Anomaly	0.3	Impossible travel detected
Time Anomaly	0.2	Unusual access time
Behavior Anomaly	0.3	Unusual action patterns

Session Actions

Action	Trigger	Response
`continue`	Risk < 0.3	Normal operation
`silent_reverify`	Risk 0.3-0.5	Background token refresh
`interactive_reverify`	Risk 0.5-0.6	Prompt for password
`step_up_auth`	Risk 0.6-0.95	Require MFA
`terminate`	Risk > 0.95	Session revoked

Step-Up Authentication Response

When step-up authentication is required:

{
  "error": "Step-up authentication required",
  "code": "STEP_UP_REQUIRED",
  "message": "Additional verification required to continue.",
  "step_up_methods": ["totp", "sms", "email"],
  "challenge_id": "challenge-abc123",
  "expires_in": 300
}

Microsegmentation

Network segment isolation for Zero Trust architecture.

Security Segments

Segment	Trust Level	Description
`public`	0.0	Unauthenticated requests
`customer`	0.3	Authenticated customers
`staff`	0.5	Restaurant staff
`manager`	0.7	Location managers
`admin`	0.8	Tenant administrators
`platform`	0.9	Platform administrators
`internal`	1.0	Service-to-service

Segment Configuration

segments:
  customer:
    allowed_endpoints:
      - /api/v1/menu/**
      - /api/v1/orders/self/**
      - /api/v1/loyalty/**
    denied_endpoints:
      - /api/v1/admin/**
      - /api/v1/internal/**
    required_roles: [customer]
    min_trust_level: 0.3
    rate_limit_rps: 100
    audit_level: basic

  staff:
    allowed_endpoints:
      - /api/v1/orders/**
      - /api/v1/tables/**
      - /api/v1/inventory/**
    denied_endpoints:
      - /api/v1/billing/**
      - /api/v1/internal/**
    required_roles: [staff, manager]
    required_shells: [staff, kds]
    min_trust_level: 0.5
    rate_limit_rps: 500
    audit_level: full

Service-to-Service Authentication

Internal microservice communication authentication.

Service Identity Token

Services authenticate using service identity tokens:

Authorization: Bearer service-token-xyz
X-Service-Name: commerce-service
X-Service-Version: 1.2.3

mTLS (Mutual TLS)

Production environments use mTLS for service mesh:

mtls:
  enabled: true
  certificate_path: /etc/certs/service.crt
  key_path: /etc/certs/service.key
  ca_path: /etc/certs/ca.crt
  verify_client: true

Service Mesh Headers

The API Gateway propagates context headers to downstream services:

Header	Description
`X-Request-ID`	Unique request identifier for tracing
`X-Correlation-ID`	Correlation ID for distributed tracing
`X-Tenant-ID`	Tenant context for multi-tenancy
`X-User-ID`	Authenticated user ID
`X-Location-ID`	Restaurant/location context
`X-Roles`	Comma-separated user roles
`X-Shell`	Active Flutter shell

Authentication Flow

Error Responses

Authentication Errors

Status	Code	Description
401	`UNAUTHORIZED`	No authentication provided
401	`INVALID_TOKEN`	Token validation failed
401	`TOKEN_EXPIRED`	Token has expired
401	`INVALID_CREDENTIALS`	Wrong username/password

Authorization Errors

Status	Code	Description
403	`FORBIDDEN`	Authenticated but not authorized
403	`INSUFFICIENT_PERMISSIONS`	Missing required role
403	`SHELL_ACCESS_DENIED`	Not authorized for shell
403	`SEGMENT_VIOLATION`	Outside allowed segment

Session Errors

Status	Code	Description
401	`SESSION_EXPIRED`	Session age exceeded
401	`SESSION_REVOKED`	Session manually terminated
403	`STEP_UP_REQUIRED`	Additional auth needed
403	`MFA_REQUIRED`	MFA verification needed

Best Practices

Token Management

Security Best Practice

Never store JWT tokens in localStorage or sessionStorage in web applications. Use secure HTTP-only cookies or in-memory storage with refresh token rotation instead.

Store securely - Use secure storage, never localStorage
Refresh proactively - Refresh 5 minutes before expiry
Handle expiration - Implement token refresh interceptor
Clear on logout - Remove all tokens on user logout

Error Handling

Retry on 401 - Attempt token refresh once
Redirect on persistent 401 - Send to login
Display 403 gracefully - Show access denied UI
Log security errors - Track for audit

Shell Context

Set shell header - Always include X-Shell or X-App-Experience
Handle shell changes - Re-authenticate on shell switch
Validate shell access - Check user's allowed shells in JWT

Authentication Overview - Auth methods and tokens
OAuth/SSO Integration - Enterprise SSO setup
MFA Configuration - Multi-factor authentication
Rate Limiting - Request throttling
API Gateway Architecture - Gateway overview

Overview​

API Key Authentication​

Headers​

Exempt Paths​

Response Codes​

Example Error Response​

JWT Authentication​

Token Format​

Authorization Header​

Context Extraction​

Token Validation​

Role-Based Access Control (RBAC)​

Predefined Roles​

Enforcement Patterns​

Single Role Requirement​

Any Role Requirement​

Ownership or Role​

Shell-Based Access Control​

Supported Shells​

Shell Header​

Shell Validation​

Shell-to-Route Mapping​

Zero Trust Continuous Authentication​

Configuration​

Risk Scoring Factors​

Session Actions​

Step-Up Authentication Response​

Microsegmentation​

Security Segments​

Segment Configuration​

Service-to-Service Authentication​

Service Identity Token​

mTLS (Mutual TLS)​

Service Mesh Headers​

Authentication Flow​

Error Responses​

Authentication Errors​

Authorization Errors​

Session Errors​

Best Practices​

Token Management​

Error Handling​

Shell Context​

Related Documentation​