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
| Provider | Token and configuration | Guide |
|---|---|---|
| Clerk | Clerk session token; server secret, issuer and authorized frontend origins | Clerk |
| Firebase | Firebase Authentication ID token; Firebase project ID | Firebase |
| OpenID Connect | Signed ID token; issuer discovery and accepted audiences | OpenID Connect |
| Custom Server | Your signed identity JWT and issuer’s JWKS endpoint | Custom 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.