Embedded token exchange

Call token exchange only from an App backend. It authenticates with the AppClient client_id and one-time-displayed client_secret over HTTP Basic. Client apps must never hold these credentials.

operationId	Method	Path
exchangeAppUserToken	POST	/api/v1/apps/{app}/token-exchange
revokeAppUserTokens	POST	/api/v1/apps/{app}/token-revoke

Exchange a token

external_user_id must match [A-Za-z0-9_\-:.]{1,128} and be pseudonymous within the Application. Do not use an email address, phone number, display name, or shared platform-wide user ID.

// App backend only. Inject clientId and clientSecret from a Secret Manager.
const server = new ServerClient({ baseUrl, applicationCode, clientId, clientSecret })
const result = await server.exchangeAppUserToken('member_42')

The successful result contains a short-lived opaque access token, lifetime in seconds, AppUser ID, and store account token. The access token is not a JWT and must not be inspected. After expiry, the App backend verifies its own user session and performs another exchange.

Return the short-lived token only over an authenticated TLS-protected app session, or proxy platform calls through the App backend. Never put it in logs, exceptions, analytics, caches, database records, or support tickets.

Revocation and rotation

On sign-out, account closure, or a security event, call revokeAppUserTokens from the App backend. Revocation is idempotent. To rotate an AppClient secret, deploy and verify the new credential before disabling the old one; remove old values from sample configuration and build artifacts.

Use Keychain, Android Keystore, or caller-controlled equivalent secure storage on the client. Official SDKs have no default persistence and do not automatically refresh access tokens.