Authentication

All RSA Platform APIs require authentication. Three tracks are available depending on your use case.

Authentication Tracks

Track	Who	Mechanism	Header
PKCE	Human users (admins, developers)	OAuth 2.0 browser redirect	`Authorization: Bearer {JWT}`
Client Credentials	Backend services, ETL	`grant_type=client_credentials`	`Authorization: Bearer {JWT}`
API Key	POS terminals, integrations	Pre-issued secret key	`X-Api-Key: rsa_live_{key}`

All three tracks produce the same JWT claim structure when inspected server-side. The Identity server issues JWT Bearer tokens signed with RS256.

Every JWT Bearer token contains:

Claim	Type	Example	Description
`sub`	string	`3fa85f64-...`	User / member identifier
`role`	string[]	`["TenantAdmin"]`	Roles assigned to this user
`scope`	string	`admin.read admin.write`	Authorized OAuth scopes
`tenant_id`	string	`c1d2e3f4-...`	Tenant UUID
`tenant_slug`	string	`cardenas`	Routes requests to correct retailer DB
`retailer_id`	string	`a1b2c3d4-...`	Retailer UUID (empty for platform users)
`email`	string	`admin@cardenas.com`	User email
`given_name`	string	`Jane`	First name
`family_name`	string	`Smith`	Last name

JWT Bearer tokens expire in 1 hour by default. Use grant_type=refresh_token to renew.
API keys do not expire but can be rotated via POST /admin/api/v1/clients/{id}/rotate-secret.

See Scopes for the full scope reference including granular aliases.

Admin portal and platform portal logins require TOTP-based MFA (RFC 6238). The setup flow:

POST /api/mfa/setup — returns a TOTP secret and QR code URI
User scans QR code with an authenticator app (Google Authenticator, 1Password, etc.)
POST /api/mfa/verify — verify first code to activate MFA

In local development, set REQUIRE_TOTP=false in the Identity API environment to bypass MFA.