> ## Documentation Index
> Fetch the complete documentation index at: https://docs.imprint.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Account Linking

> Connect your customers' loyalty or identity accounts with their Imprint card account

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:

| Item                       | Description                                                                                |
| -------------------------- | ------------------------------------------------------------------------------------------ |
| **Client ID**              | The OAuth client identifier issued to Imprint                                              |
| **Client Secret**          | Required if using a confidential client. Not needed for public clients (PKCE-only).        |
| **Authorization endpoint** | Your login/authorize URL where users are redirected to sign in                             |
| **Token endpoint**         | Your token exchange URL where Imprint exchanges the authorization code for an access token |

<Info>
  Please send credentials over a secure medium (e.g. a secrets manager, encrypted channel). Do not send client secrets in plain text over email.
</Info>

### 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)

<Note>
  Replace `{merchant_key}` with your assigned merchant key (provided by Imprint during onboarding).
</Note>

### 3. Identity resolution

Imprint needs to resolve the authenticated user's identity on your side. There are two supported modes:

<Tabs>
  <Tab title="OIDC">
    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`).
  </Tab>

  <Tab title="OAuth 2.0">
    If your identity provider supports **OAuth 2.0** but does not support OIDC:

    * Provide an **identity endpoint** URL that Imprint can call with `Authorization: Bearer <access_token>` to resolve the user.
    * The endpoint must return: `{"partner_customer_id": "<value>"}`
    * The endpoint must be **HTTPS**.
    * Provide the exact **scope** values required to call the identity endpoint.
    * Confirm your token endpoint's **client authentication method**: form body or none (public client with PKCE only).
  </Tab>
</Tabs>

### 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Token exchange">
    Imprint exchanges the authorization code at your token endpoint for an access token (and ID token, if OIDC).
  </Step>

  <Step title="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).
  </Step>

  <Step title="Link created">
    The customer's Imprint account is linked to their partner identity. A `CUSTOMER_LINK` webhook event is fired to notify your systems.
  </Step>
</Steps>

## 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`](/event-notifications) webhook event containing the linked customer details. Subscribe to this event to update your systems when a cardholder links their account.