Authentication

Octomil uses three authentication mechanisms: API keys for server-to-server calls, device tokens for on-device SDKs, and JWT-based sessions for the dashboard.

API Keys

API keys authenticate control-plane requests (model management, rollouts, federation operations). Keys are scoped to an organization and carry permission scopes.

Creating keys

CLI

octomil api-keys create --name "ci-pipeline" --scopes models:read,models:write,rollouts:write

Dashboard

Navigate to Settings > API Keys > Create Key. Select the scopes required for your use case.

Scopes

Scope	Access
models:read	List and retrieve models and versions
models:write	Create models, upload versions
devices:read	List and retrieve devices
devices:write	Register devices, manage groups
rollouts:write	Create and delete rollouts
federations:admin	Full federation management
training:write	Start rounds, configure strategies
experiments:write	Create and manage experiments

Using keys

curl https://api.octomil.com/api/v1/models \
  -H "Authorization: Bearer edg_live_your_key_here"

Keys are prefixed edg_live_ (production) or edg_test_ (sandbox).

Device Tokens

Device tokens authenticate mobile and edge devices. The lifecycle is: bootstrap, refresh, revoke.

Bootstrap flow

1. Device calls POST /api/v1/devices/register with a bootstrap token (embedded in the app binary or fetched from your backend).
2. Server returns a device-specific API key and a refresh token.
3. SDK stores the key in the platform keychain (iOS Keychain, Android Keystore).

iOS

let client = OctomilClient(bootstrapToken: "edg_bootstrap_...")
try await client.register(deviceId: UIDevice.current.identifierForVendor!.uuidString)
// Key stored in iOS Keychain automatically

Android

val client = OctomilClient(bootstrapToken = "edg_bootstrap_...")
client.register(deviceId = Settings.Secure.ANDROID_ID)
// Key stored in Android Keystore automatically

Token refresh

Tokens expire after 24 hours by default. SDKs handle refresh automatically using the refresh token. Configure expiry via the dashboard or CLI:

octomil org settings --device-token-expiry 48h

Revocation

Revoke a device token to immediately block a device from participating in training or receiving model updates:

octomil devices revoke <device-id>

RBAC

Octomil uses three organization roles.

Role	Permissions
Owner	Full access. Billing, member management, delete org.
Admin	Manage models, devices, rollouts, experiments. Cannot delete org or manage billing.
Member	Read-only access to models and devices. Can submit training updates.

Assigning roles

octomil org members add user@example.com --role admin
octomil org members update user@example.com --role member

Compliance presets and MFA

HIPAA and PCI presets enforce MFA for all users. GDPR and SOC 2 presets enforce MFA for admins only. See Compliance for details.

Rate Limits

Surface	Limit
Control plane (per device)	100 req/min
Inference (per key)	1000 req/min
Device registration	10 req/min per IP

Rate-limited responses return 429 with a Retry-After header.