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 member. Account Linking uses OpenID Connect (OIDC). Imprint acts as an OIDC relying party against your identity provider: Imprint redirects the member to your authorization endpoint; after they authenticate, you redirect back to Imprint with an authorization code. Imprint exchanges that code at your token endpoint for an ID token, verifies it, reads the customer’s identity from it, and creates the link.
OIDC and OAuth 2.0 — how to read this page. OIDC is not an alternative to OAuth 2.0; it is the identity layer standardized on top of OAuth 2.0. So OAuth 2.0 terms appear throughout this page — the authorization code grant, the token endpoint, PKCE. In every case they refer to the OAuth 2.0 mechanism as profiled by OIDC, not to a separate OAuth-only integration.Only the last row conveys identity. That is why Imprint requires OIDC: an OAuth 2.0 access token on its own proves authorization, not who the member is.

​
What you need to provide

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

​
1. OIDC client application

Register an OIDC client application for Imprint in your identity provider (or provide credentials to an existing one). These are the standard OAuth 2.0 client-registration fields that OIDC reuses unchanged. The client ID and both endpoints are always required; the client secret only for confidential clients. Send the endpoints even if you publish a discovery document — Imprint configures them explicitly rather than reading them from discovery:
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 client application to allow-list the following redirect URIs. These are where your system redirects members 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 resolves the authenticated member’s identity from the OIDC ID token returned by your token endpoint. Provide:
  • Your OIDC discovery URL (.well-known/openid-configuration). Imprint reads your issuer and jwks_uri from it to verify ID token signatures. It does not source the authorization or token endpoints from discovery — those are the separately configured values in section 1, which remain required.
  • The openid scope, which must be grantable to Imprint’s client. Include any additional scopes your provider requires to issue an ID token.
  • A stable, non-reassignable identifier in the ID token’s sub claim. This becomes the partner customer ID Imprint stores against the link, so it must not change if the member updates their email, username, or phone number.
  • nonce echoed into the ID token. Imprint sends a single-use nonce on the authorization request; your provider must return it unchanged as the ID token’s nonce claim. Imprint rejects any ID token whose nonce is missing, empty, or does not match — this is the most common cause of a flow that authenticates successfully but fails at the final step.
  • Your client authentication method at the token endpoint: client_secret_post (confidential client) or none (public client, PKCE required).
Imprint reads identity only from the verified ID token’s sub claim. Imprint does not call a separate userinfo or custom identity endpoint to determine who the member is, so no such endpoint is required. If your provider cannot issue an ID token with a stable sub, contact Imprint before starting integration.

​
4. PKCE support

Confirm whether your token endpoint supports PKCE (Proof Key for Code Exchange, RFC 7636) with the S256 challenge method. Imprint configures PKCE per product as either S256 or disabled. PKCE is an OAuth 2.0 extension rather than part of the OIDC specification, but it applies to the OIDC Authorization Code Flow exactly as it does to a plain OAuth 2.0 one — OIDC inherits it. When S256 is configured for your product, Imprint sends code_challenge / code_challenge_method=S256 on the authorization request and code_verifier on the token exchange; when PKCE is disabled, it sends none of these. PKCE is required for public clients (none client authentication) and strongly preferred for confidential clients, as it protects against authorization code interception.

​
5. Test credentials

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

​
6. Framing requirements (Web SDK)

When the member links their account from the Web SDK, the entire experience — including the redirect to your authorization/login page — runs inside an <iframe> embedded on the partner page. Your authorization endpoint, and every page in the redirect chain (login page, consent screen, any interstitial or identity-provider hosted page), must therefore be allowed to render inside a frame.
A page that returns X-Frame-Options: DENY or X-Frame-Options: SAMEORIGIN, or a Content-Security-Policy: frame-ancestors directive that excludes Imprint’s origin, will be blocked by the browser. The member sees a blank frame, the sign-in flow cannot complete, and the SDK cannot detect or report the failure — it looks like the flow silently hung.
To support the Web SDK, explicitly allow Imprint’s Web SDK origin on every page in your sign-in flow via a CSP frame-ancestors directive. Do not use X-Frame-Options, which has no allow-list mechanism beyond SAMEORIGIN and cannot permit a cross-origin frame: Sandbox:
Production:
When both X-Frame-Options and CSP frame-ancestors are present, modern browsers honor frame-ancestors and ignore X-Frame-Options. However, some environments and security proxies still enforce X-Frame-Options, so the safest configuration is to remove X-Frame-Options entirely on the pages in your linking flow and rely on frame-ancestors.
These framing requirements — the frame-ancestors allow-list and the X-Frame-Options caveats above — apply only to the Web SDK. The iOS and Android SDKs present the linking flow in a native view (and use the imprint:// / imprint-sbx:// deep links), so they are not framed and are unaffected by X-Frame-Options / CSP frame-ancestors headers.

​
How the flow works

1

User initiates linking

The member taps “Link Account” in the Imprint app. Imprint generates a secure state token and a single-use nonce, then redirects the user to your authorization endpoint with both.
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 ID token (sending the PKCE code_verifier when S256 is configured), then verifies the token’s signature against your JWKS along with its issuer, audience, expiry, and nonce.
4

Identity resolution

Imprint reads the partner customer ID from the sub claim of the verified ID token.
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. Your OIDC discovery document is reachable and returns an issuer and a jwks_uri.
  2. Redirect to your authorization endpoint succeeds and returns code + state.
  3. Token exchange succeeds (with the PKCE code_verifier when S256 is configured) and returns an ID token.
  4. The ID token verifies — signature against your JWKS, plus issuer, audience, expiry, and a nonce matching the one Imprint sent.
  5. The sub claim yields a valid, stable partner customer ID.
  6. The link is created and the 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 member links their account.