Security Architecture

This document describes the security architecture of the Octomil platform. It covers how identity, authorization, tenant isolation, key management, and auditing work together to protect federated learning workloads where sensitive data never leaves edge devices.

Architecture Overview

The security model is organized in four layers. Each layer operates independently so that a compromise in one layer does not automatically grant access to another.

Identity and Access

• User auth: passkeys/OAuth or enterprise SSO
• Device auth: short-lived device access tokens + refresh tokens
• Authorization: org-scoped RBAC (owner, admin, member) and scoped API/device tokens

API Authentication Flow

All API requests must include a valid credential. The server validates credentials in this order:

1. Bearer token: Extracted from the Authorization header. The server validates the token signature, expiry, and organization scope. Used by dashboard sessions and SDK clients.
2. API key: Extracted from the X-API-Key header. The server validates the key and looks up the corresponding org and scopes. Used for server-to-server integrations.
3. Device token: Extracted from the Authorization header with a device identifier. The server validates the token and checks that the device is registered and active. Used by mobile and edge SDKs.

If no valid credential is found, the server returns 401 Unauthorized. If the credential is valid but the user lacks permission for the requested resource, the server returns 403 Forbidden.

Device Authentication Flow

Device authentication uses a two-phase flow to avoid embedding long-lived secrets on untrusted hardware. See Device Token Lifecycle for the full flow.

1. Bootstrap phase: The backend (trusted) calls Octomil with an org API key to obtain a short-lived bootstrap token. This token is passed to the device through a secure channel (e.g., app provisioning, QR code, MDM push).
2. Exchange phase: The device SDK sends the bootstrap token to /api/v1/device-auth/bootstrap. The server validates the token, registers the device, and returns an access token + refresh token pair.
3. Operational phase: The device uses the access token for all API calls. When the access token expires, the SDK transparently refreshes it using the refresh token.

Token Lifecycle Overview

Token Type	Issued By	TTL	Refresh	Revocable
User session token	Auth service	Configurable	Via session cookie	Yes, via logout or admin revoke
API key	Admin via dashboard	No expiry (rotate manually)	N/A	Yes, via dashboard or API
Device bootstrap token	Backend service	Short-lived	No	Yes, single-use
Device access token	Octomil server	Short-lived (configurable)	Via refresh token	Yes, via SDK or admin
Device refresh token	Octomil server	Long-lived (configurable)	On use (rotated)	Yes, via SDK or admin

RBAC Roles and Scopes

Role	Scope	Capabilities
owner	Full	All operations including billing, workspace deletion, member management
admin	Management	Device management, model uploads, experiment creation, member invites
member	Operational	View dashboard, submit training updates, view models and experiments

Scoped API tokens can further restrict access. For example, a token with devices:read scope can list devices but cannot register new ones. Scopes are enforced at the router level.

Tenant Isolation

• Resource access is org-boundary enforced at API layer
• Cross-tenant reads/writes are denied by org checks and role gates

How Tenant Isolation Works

Every resource query is automatically scoped to the caller's organization. The org_id is extracted from the authenticated token and injected into every database query at the service layer — not just the API layer. There is no API endpoint that accepts org_id as a request parameter; it always comes from the token. This prevents parameter tampering.

Cross-Tenant Protection

• Model artifacts are stored under org-specific prefixes with access controls
• All database records are scoped to the owning organization
• Background jobs validate organization ownership before processing

Key Material and Secrets

• Backend API keys remain server-side only
• Device bootstrap token is short-lived and exchanged for device auth session
• Secrets are stored in deployment secret manager (never in client apps)

Secret Storage by Environment

Secret	Development	Production
JWT signing key	Auto-generated fallback	Secret manager
Database credentials	Local config (gitignored)	Secret manager
Storage credentials	Local config (gitignored)	Cloud IAM role
Third-party API keys	Local config (gitignored)	Secret manager

In production, the server reads secrets from environment variables injected by the deployment platform. Secrets are never logged, never included in error responses, and never stored in the database.

Key Rotation

• JWT signing keys: Rotate quarterly. The server supports graceful key rotation with no downtime.
• API keys: Rotate on compromise or quarterly. Use the dashboard to generate a new key and deprecate the old one.
• Database credentials: Rotate via your deployment platform's secret rotation mechanism.

Network Security

TLS

All traffic between clients and the Octomil API is encrypted with TLS 1.2 or higher. The platform enforces HTTPS and returns HSTS headers.

• Client-to-API: TLS terminated at the load balancer
• API-to-database: TLS enforced on all database connections
• API-to-storage: HTTPS enforced for all object storage operations

Rate Limiting

Rate limiting is enforced per-org and per-IP to prevent abuse. Limits vary by endpoint category, with stricter limits on authentication endpoints and more permissive limits on training data submission. Rate limit responses include Retry-After headers.

Data Encryption

At Rest

• Database: Disk-level encryption via the hosting provider
• Model artifacts: Server-side encryption in object storage
• Backups: Encrypted using the same key management as the source

In Transit

• All API traffic: TLS 1.2+
• Device-to-server model updates: TLS 1.2+ with certificate pinning available in mobile SDKs
• Inter-service traffic (when applicable): Encrypted inter-service communication

On Device

Training data never leaves the device. The only data transmitted to the server is:

• Model weight updates (gradients or updated parameters)
• Training metrics (loss, accuracy, sample count)
• Device telemetry (hardware class, OS version, battery level)

The Privacy Guide describes additional protections (differential privacy, secure aggregation) applied to weight updates before transmission.

Auditing

• Identity lifecycle actions are written to audit events
• SCIM sync and onboarding identity actions are logged with metadata

What is Audited

Event Category	Examples	Retention
Authentication	Login, logout, failed login, MFA challenge	Configurable per compliance preset
Authorization	Permission denied, role change, scope violation	Configurable per compliance preset
Device lifecycle	Registration, deprovisioning, token revocation	Configurable per compliance preset
Model operations	Upload, deploy, rollback, delete	Configurable per compliance preset
Admin actions	Member invite, role assignment, workspace settings change	Configurable per compliance preset
SCIM events	User provisioned, deprovisioned, attribute sync	Configurable per compliance preset

Audit logs are queryable via the Logs and Audit dashboard and the /api/v1/audit/events API endpoint.

Threat Model

Threat	Mitigation
Stolen device with cached tokens	Short-lived access tokens. Refresh token revocable by admin. Platform-specific secure storage (Keychain, Keystore).
Compromised API key	API keys are org-scoped and revocable. Use device tokens for client-side code instead. See Migration from Org API Keys.
Model poisoning (malicious weight updates)	Byzantine-robust aggregation strategies detect and reject poisoned updates. See Advanced FL Strategies.
Gradient inversion attacks	Differential privacy (gradient clipping + noise injection). See Privacy Guide.
Cross-tenant data leakage	Org-scoped queries at service layer. No shared model storage paths.
Insider threat (compromised admin)	Audit logging on all admin actions. MFA enforcement. Explicit provisioning for elevated roles.

Recommended Hardening

• Enforce MFA for admins
• Enable explicit admin provisioning for elevated roles
• Rotate backend API keys on schedule
• Set org-specific retention in workspace settings

Production Security Checklist

• TLS enforced on all endpoints (no HTTP fallback)
• JWT signing key stored in secret manager (not environment file)
• Database credentials rotated and stored in secret manager
• MFA enforced for all admin and owner roles
• SCIM deprovisioning tested and verified
• Rate limiting enabled on authentication endpoints
• Audit log retention configured per compliance requirements
• Device token revocation tested in incident drill
• S3 bucket policies restrict access to org-specific prefixes
• No API keys embedded in client applications (use device token flow)
• Alerts configured for auth failure spikes

Related Docs

• Admin Onboarding: SSO + SCIM -- enterprise identity configuration
• Device Token Lifecycle -- device authentication details
• Migration from Org API Keys -- removing embedded secrets
• Privacy Guide -- data privacy guarantees
• Advanced FL Strategies -- defense against malicious participants
• API Reference -- full endpoint documentation