Skip to Content

Customer authentication

Your Modem account manages projects. Your app’s users are customers of a project. Signing in to Modem does not sign a customer in to your app, and an admin API key is not a customer access token.

Connect an authentication provider in Projects → your project → General → Authentication. Then give the Client SDK a fresh identity token from that provider. Modem verifies the token, identifies the customer within that project and issues its own session for the Client API and gateway.

Choose a provider

ProviderToken and configurationGuide
ClerkClerk session token; server secret, issuer and authorized frontend originsClerk
FirebaseFirebase Authentication ID token; Firebase project IDFirebase
OpenID ConnectSigned ID token; issuer discovery and accepted audiencesOpenID Connect
Custom ServerYour signed identity JWT and issuer’s JWKS endpointCustom Server

The settings also expose an App Store authentication connection, but it is not a supported identity-token adapter for client.session.establish(). Use Clerk, Firebase, OIDC or Custom Server JWTs for the customer-session flow documented here. Handle StoreKit purchases through App Store billing; enabling the authentication connection does not establish a customer session or configure purchase verification.

A project can have multiple provider connections, including multiple OIDC issuers. Modem selects the configured connection from the token’s issuer, then verifies the signature and provider-specific requirements. An unverified issuer field only selects the verifier; it does not authenticate the customer.

Connect the Client SDK

import { createCustomerClient } from '@preternatural-js/client-sdk' const client = createCustomerClient({ environment: 'production', projectId: 'YOUR_PROJECT_ID', authentication: { type: 'identity-token-provider', getIdentityToken: async () => { // Return a current token from the configured provider. return await getSignedInUsersIdentityToken() } } }) await client.session.establish()

getSignedInUsersIdentityToken is your app’s function; the provider guides show what it should return. Do not return a provider API secret, a Modem admin key or an unrelated OAuth access token. See Client SDK authentication for session storage, renewal, switching users and handling access changes.

Identity namespaces

Provider identity is scoped to its connection and project. Matching email addresses do not prove that two provider subjects are the same customer. Keep your app’s own user mapping explicit when supporting multiple providers; do not implement account linking by comparing email text.

Treat changing issuer, disconnecting a provider and removing a customer as access changes, not cosmetic settings edits. Provider lifecycle explains the purchase guards, deprovisioning and reconnection behavior.

Troubleshooting

  • Invalid identification token: acquire a fresh token from the intended provider instance. Check issuer, audience, expiry and signing algorithm for that provider.
  • Provider not configured: check the selected project and environment, then compare the token issuer with that project’s connection.
  • Verification temporarily unavailable: a discovery or signing-key service can be unavailable. This is different from an invalid user; retain the sign-in UI and offer a retry.
  • Customer suspended or identity revoked: do not keep requesting replacement sessions with the same token. Resolve the lifecycle state described in provider lifecycle.
Last updated on