> For the complete documentation index, see [llms.txt](https://docs.perkville.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perkville.com/integrations/perkville-external-reward-provider-customer-handoff.md).

# Perkville → external reward provider customer handoff

### Goal

Let a customer already authenticated in a partner app ("App A") open an external reward provider's platform as the correct customer without another login. Perkville supplies an encrypted identity token. The provider validates it, establishes the customer session, and opens the appropriate storefront.

The token identifies the customer and business. Customers choose rewards in the provider's platform, and redemptions continue through the existing authorization and eligibility checks.

### Who implements each part

The partner app and the external reward provider may be operated by different companies.

* **Partner app ("App A")**: Displays rewards, requests a fresh SSO launch URL from its backend when the customer selects an external reward (step 2 below), and opens the returned URL. It uses its Perkville admin API credentials for the API request.
* **External reward provider**: Receives the customer on its platform, validates and decrypts the token, and establishes the customer session. **Only the external reward provider needs to complete the secure encryption key exchange with Perkville.**
* **Perkville**: Checks authorization and generates the encrypted token and SSO launch URL.

App A does not need the provider's shared encryption key and does not decrypt the token. Its Perkville API credentials are separate from the encryption key exchanged between Perkville and the provider.

### End-to-end flow<br>

1. **App A displays rewards** using Perkville's API. It may cache the ordinary reward listing, including the existing external reward URL.
2. **The customer taps an external reward**. App A's backend requests a fresh SSO link from Perkville for its authenticated customer and the selected external reward entry. App A keeps its admin API credentials on its backend.
   1. To request a link, please follow the instructions laid out in the [Redeeming View API](https://www.perkville.com/developers/docs/v2/#v2_rewards_program_redeeming_view_anchor).
3. **Perkville checks authorization** for the API client, business admin, customer, and visible external reward. It returns a separate, two-minute SSO launch URL. The configured reward URL remains unchanged.
4. **App A opens the launch URL**, for example:\
   `https://sso.provider.example/launch?metric=<encrypted-token>`
5. **The provider validates the token and destination**, consumes the token once, and creates a session for the identified customer. It then directs the customer to the destination storefront, handling any required cross-domain session transfer.
6. **For integrations using API-only rewards, the provider redeems points and fulfills the selected reward.** It uses its own authorized API client and a business-owned [API-only reward](https://docs.perkville.com/features/redeeming-rules/external-rewards/api-only-rewards.md). This is a separate API transaction after the handoff.

App A fetches a new link on each click to ensure a fresh token is generated. The provider does not need to call Perkville to decrypt the token; it uses the shared encryption key provisioned during setup. No pending session or cookie shared with App A is required.

### Redeeming points after the handoff

The identity token establishes who the customer is; it does not authorize a points redemption. The provider's API client needs the appropriate API permissions and explicit access to the business's API-only reward. App A's permission to request a launch URL does not grant the provider permission to redeem.

See [API-only rewards](https://docs.perkville.com/features/redeeming-rules/external-rewards/api-only-rewards.md) for business setup, allowed API clients, points and quantity, eligibility, and fulfillment responsibilities.

### What Perkville sends

The \`metric\` parameter contains five dot-separated components:

`v1.<key_id>.<nonce>.<ciphertext>.<tag>`

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Item</strong></td><td><strong>Contract</strong></td></tr><tr><td>Encryption</td><td><code>AES-256-GCM</code> with a 32-byte shared key</td></tr><tr><td>Nonce</td><td>12 fresh random bytes per token</td></tr><tr><td>Authentication tag</td><td>16 bytes</td></tr><tr><td>Authenticated header / AAD</td><td>Exact ASCII bytes of <code>v1.&#x3C;key_id></code></td></tr><tr><td>Binary encoding</td><td><code>Nonce</code>, <code>ciphertext</code>, and <code>tag</code> each use unpadded <code>Base64url</code></td></tr><tr><td>Plaintext</td><td><code>UTF-8 JSON</code></td></tr><tr><td>Lifetime</td><td>120 seconds from issuance</td></tr></tbody></table>

This is a custom AES-GCM envelope, not a JWT. GCM provides both encryption and tamper detection. The provider must verify the authentication tag before using the plaintext.

Illustrative decrypted payload (example timestamps are not live credentials):

```json
{
  "user_id": 123,
  "business_id": 89,
  "destination_url": "https://custom-client.example/store",
  "iat": 1735689600,
  "exp": 1735689720,
  "token_id": "SkpKSkpKSkpKSkpKSkpKSg"
}
```

* `user_id` and `business_id` are positive integer Perkville IDs.
* `iat` and `exp` are integer `Unix` timestamps in UTC.
  * `iat` is the issued at time.
  * `exp` is the expiration time.
* `token_id` uniquely identifies this handoff: 16 random bytes encoded as Base64url.
* `destination_url` is the original configured reward URL, including its path, query parameters, and fragment if present.

### Provider validation and session handling

The provider completes these checks before signing the customer in:

1. **Verify the token**: Decrypt and authenticate it with the dedicated integration key using the contract above. Validate the required payload fields and their types.
2. **Check the time**: Enforce the two-minute lifetime and reject expired or future-dated tokens outside the agreed clock tolerance (proposed: 30 seconds).
3. **Confirm the destination**: Resolve the customer and confirm the HTTPS storefront is managed by the provider and authorized for that business.
4. **Enforce single use**: Atomically record token\_id within the configured provider and environment across servers until expiry plus tolerance. Reject duplicates or unavailable replay checks.
5. **Sign in and redirect**: Establish a secure session and open the storefront without forwarding the original token. The provider handles session transfer for custom domains.

Treat launch links as credentials: exclude them from logs and analytics, and use `Cache-Control: no-store` and `Referrer-Policy: no-referrer`. If validation fails, ask the customer to return to the app for a fresh link.

### Implementation setup and secure key exchange

The external reward provider should contact <api@perkville.com> for implementation details and to arrange the secure encryption key exchange with Perkville. If the partner app is operated by a separate company, that app team does not need to participate in the encryption key exchange; it implements the app-side flow above, including the fresh SSO link request in step 2.

For coordination, include the app team and the external reward provider in the implementation discussion with <api@perkville.com> so each team understands its responsibilities.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.perkville.com/integrations/perkville-external-reward-provider-customer-handoff.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
