Skip to main content
Account Linking lets you connect a customer’s identity in your system (e.g. loyalty account, membership) to their Imprint card account. Once linked, Imprint can credit partner-owned rewards and display membership status to the cardholder. The flow uses a standard OAuth 2.0 Authorization Code grant. Imprint redirects the cardholder to your login page; after they authenticate, you redirect back to Imprint with an authorization code. Imprint exchanges the code for an access token, resolves the customer’s identity, and creates the link.

​
What you need to provide

To set up Account Linking, provide the following to Imprint for each environment (sandbox and production):

​
1. OAuth client application

Create an OAuth client application for Imprint in your identity provider (or provide credentials to an existing one). Provide:
ItemDescription
Client IDThe OAuth client identifier issued to Imprint
Client SecretRequired if using a confidential client. Not needed for public clients (PKCE-only).
Authorization endpointYour login/authorize URL where users are redirected to sign in
Token endpointYour token exchange URL where Imprint exchanges the authorization code for an access token
Please send credentials over a secure medium (e.g. a secrets manager, encrypted channel). Do not send client secrets in plain text over email.

​
2. Redirect URIs

Configure your OAuth application to allow-list the following redirect URIs. These are where your system redirects users back to Imprint after authentication. Sandbox:
  • https://apply.sbx.imprint.co/link-account/{merchant_key}
  • https://account.sbx.imprint.co/link-account/{merchant_key}
  • imprint-sbx://link-account (mobile deep link)
Production:
  • https://apply.imprint.co/link-account/{merchant_key}
  • https://account.imprint.co/link-account/{merchant_key}
  • imprint://link-account (mobile deep link)
Replace {merchant_key} with your assigned merchant key (provided by Imprint during onboarding).

​
3. Identity resolution

Imprint needs to resolve the authenticated user’s identity on your side. There are two supported modes:
If your identity provider supports OpenID Connect:
  • Provide your OIDC discovery URL (.well-known/openid-configuration). Imprint uses this to fetch your issuer and JWKS for ID token verification.
  • Set scope to openid.
  • The stable user identifier must be available in the sub claim of the ID token.
  • Client must be configured as a confidential client (with a client_secret).

​
4. PKCE support

Confirm whether your OAuth implementation supports PKCE (Proof Key for Code Exchange) with the S256 challenge method. PKCE is strongly preferred as it protects against authorization code interception.

​
5. Test credentials

Provide a test user (or test tenant) in your identity provider so Imprint can complete end-to-end testing of the redirect, token exchange, and identity resolution.

​
How the flow works

1

User initiates linking

The cardholder taps “Link Account” in the Imprint app. Imprint generates a secure state token and redirects the user to your authorization endpoint.
2

User authenticates

The user signs in on your login page (or an existing session is reused). Your system redirects back to Imprint’s redirect URI with an authorization code and state.
3

Token exchange

Imprint exchanges the authorization code at your token endpoint for an access token (and ID token, if OIDC).
4

Identity resolution

Imprint resolves the partner customer ID — either from the sub claim in the ID token (OIDC) or by calling your identity endpoint with the access token (OAuth 2.0).
5

Link created

The customer’s Imprint account is linked to their partner identity. A CUSTOMER_LINK webhook event is fired to notify your systems.

​
What we validate in testing

Once configuration is complete, Imprint will verify:
  1. Redirect to your authorization endpoint succeeds and returns code + state.
  2. Token exchange succeeds (with PKCE code_verifier if S256 is configured).
  3. Identity resolution returns a valid, stable partner customer ID.
  4. The link is created and CUSTOMER_LINK webhook fires successfully.

​
Webhook notification

After a successful link, Imprint sends a CUSTOMER_LINK webhook event containing the linked customer details. Subscribe to this event to update your systems when a cardholder links their account.