PLATFORM API Live

Authentication and tenant isolation

Use Cognito OAuth for platform users, one-time tokens for enrolment, device credentials for heartbeats and read-only personal tokens for MCP.

Last updated 27 July 2026 · Documentation version 2026.07

Oddessy authentication flows for interactive Cognito users, expiring read-only agent tokens and enrolled edge-device credentials resolving to tenant-owned resources — Different actors use different credentials, but every validated identity resolves to one owner partition.

Interactive users

The Platform uses the OAuth authorization-code flow with PKCE against an invite-only Amazon Cognito user pool. ID and access tokens are short lived; browser tokens remain in session storage.

Authorization: Bearer <Cognito ID token for Platform API>

Agent tokens

Personal API tokens begin with odd_pat_, are shown once, stored only as SHA-256 hashes and limited to read-only MCP scopes. They can be revoked immediately from the Account page.

Authorization: Bearer odd_pat_...

Devices

After one-time enrolment, the device uses its ID plus a high-entropy credential on each outbound heartbeat.

X-Oddessy-Device-Id: odd-example123
Authorization: Device <device credential>

Tenant boundary

User and agent identities resolve to the same Cognito subject. DynamoDB lookups use that subject as the partition key; a supplied device ID cannot cross the owner partition.

Never put tokens in URLs

Use the Authorization header and a client secret store. Do not place personal tokens in query strings, documentation snippets, screenshots or source control.