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

# Security, privacy, and data handling

> Understand Perkstar's security boundaries, privacy roles, retention rules, and integration responsibilities.

This page is the technical data-handling summary for teams integrating with
Perkstar. The [Privacy Notice](https://dashboard.perkstar.co.uk/privacy),
[Data Processing Agreement](https://dashboard.perkstar.co.uk/dpa), and
[sub-processor list](https://dashboard.perkstar.co.uk/dpa/sub-processors) are
the governing documents.

<Note>
  This page explains product behaviour; it is not legal advice and does not
  replace your own privacy, security, or regulatory review.
</Note>

## Responsibility model

```mermaid theme={null}
flowchart LR
  Customer["Cardholder"] --> Business["Business using Perkstar\nNormally the data controller"]
  Business --> Perkstar["Perkstar\nNormally the data processor"]
  Perkstar --> Provider["Approved sub-processors\nand enabled integrations"]
  Partner["Your integration"] <--> Perkstar
  Business --> Partner
```

For cardholder loyalty data, the business normally decides why data is
processed, what is collected, which messages are sent, and which integrations
are enabled. Perkstar normally processes that data for the business. Perkstar
acts as controller for limited platform purposes such as account
administration, billing, support, security, fraud prevention, and legal
compliance.

Your organisation is responsible for determining its role for data copied to
or from its integration, documenting a lawful purpose, and honouring deletion,
access, correction, consent, and objection requests.

## Data an integration can handle

| Category                      | Typical fields                                                       | Minimise it by                                                             |
| ----------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Customer identity             | Name, email, phone, date of birth, external reference                | Requesting only the scopes and fields needed for the workflow              |
| Loyalty activity              | Card, enrolment, balance, transaction, reward and redemption records | Storing Perkstar IDs instead of duplicating full profiles                  |
| Consent                       | Marketing and ad-tracking flags, consent history                     | Treating flags as purpose-specific evidence, not blanket permission        |
| Location and commerce context | Location ID, amount, order or transaction reference                  | Sending stable references and required totals, not full baskets by default |
| Credentials                   | API keys, OAuth access/refresh tokens, webhook secrets               | Keeping secrets in a server-side secret manager and never in client code   |
| Operational metadata          | Request IDs, status codes, delivery IDs, timestamps                  | Avoiding raw payloads in logs unless needed and access-controlled          |

## Security boundaries

<CardGroup cols={2}>
  <Card title="Tenant isolation" icon="building-shield">
    Credentials resolve to one organisation. Resource queries and mutations are
    checked against that organisation at the API boundary.
  </Card>

  <Card title="Least privilege" icon="key">
    API keys and OAuth grants carry explicit scopes. Create a separate
    credential for each integration and environment.
  </Card>

  <Card title="Secrets at rest" icon="lock">
    API keys, client secrets, authorization codes, and OAuth tokens are stored
    as non-reversible hashes where they only need comparison. Provider
    credentials that must be reused are encrypted.
  </Card>

  <Card title="Transport and callbacks" icon="shield-check">
    Production traffic uses HTTPS. OAuth redirect URIs match exactly; webhooks
    are HMAC signed and outbound URLs are checked against private-network and
    DNS-rebinding targets.
  </Card>

  <Card title="Retry safety" icon="rotate">
    POST requests use idempotency keys, POS transactions support permanent
    external-reference deduplication, and OAuth refresh tokens rotate once.
  </Card>

  <Card title="Auditability" icon="list-check">
    API responses include `X-Request-Id`; authenticated API activity is kept in
    a bounded audit trail for investigation and support.
  </Card>
</CardGroup>

## Credential handling

1. Create separate test and live credentials.
2. Grant only the scopes required by the job.
3. Store plaintext secrets immediately; Perkstar cannot reveal them again.
4. Never place a key or client secret in browser JavaScript, a mobile bundle,
   source control, analytics, screenshots, or support messages.
5. Rotate on suspected exposure and revoke credentials when an integration is
   disconnected.
6. Treat webhook bodies and OAuth tokens as personal or confidential data when
   they can be linked to a customer or business.

See [Authentication and scopes](/fundamentals/authentication) and the
[OAuth marketplace guide](/guides/oauth-marketplace) for implementation
details.

## Consent and communications

Customer profile fields and consent flags can be written by an authorised
integration. A flag records the state supplied to Perkstar; it does not prove
that your external system collected valid consent. Keep the source, wording,
time, and lawful basis needed for your own audit.

Marketing wallet pushes require push-marketing consent. Transactional wallet
updates needed to keep a pass accurate are separate from promotional
communications. Do not infer email or SMS permission from a wallet install.

## Retention and deletion

| Record                            | Current operational rule                                                               |
| --------------------------------- | -------------------------------------------------------------------------------------- |
| Active customer profile           | Kept while the operator account and loyalty relationship are active                    |
| Cancelled-account cardholder data | 90-day grace period, then anonymised or deleted where no legal hold applies            |
| Pseudonymised transaction residue | Up to the applicable accounting/legal period, usually up to six years for UK operators |
| Data-export archive               | Expires after 48 hours and uses a single-use link                                      |
| Security and rate-limit logs      | Normally 90 days unless required for an investigation                                  |
| API request audit                 | Rolling seven-day operational window                                                   |
| Production backups                | Rolling seven days                                                                     |
| Marketing suppression evidence    | Kept as needed to prevent accidental re-contact                                        |

Customer erasure is implemented as anonymisation when financial or audit facts
must remain. Direct identifiers are removed while the minimum pseudonymised
ledger can be retained. `DELETE /customers/{id}` exposes that workflow to a
properly scoped integration.

<Warning>
  Deleting data from your integration does not delete it from Perkstar, and
  anonymising it in Perkstar does not automatically erase an uncontrolled copy
  in your system. Design and test propagation in both directions.
</Warning>

## Webhook and OAuth data

* Verify webhook signatures against the exact raw body before parsing.
* Deduplicate with the stable webhook event ID and restrict access to stored
  delivery payloads.
* OAuth access tokens expire after one hour. Refresh tokens rotate and must be
  replaced atomically; replay revokes the grant.
* Revoking either an access or refresh token revokes the paired grant.
* A marketplace uninstall should stop jobs, revoke tokens, remove unnecessary
  cached personal data, and retain only the audit facts your policy requires.

## Rights requests and incidents

Businesses can export and anonymise customer data in the dashboard, and
customers can use the privacy controls linked from their pass. Integration
teams should be able to locate records by Perkstar ID and external reference,
export a readable copy, correct a mismatch, and erase or suppress downstream
copies.

Report suspected credential exposure, unauthorised access, or a personal-data
incident immediately to [privacy@perkstar.co.uk](mailto:privacy@perkstar.co.uk).
For API implementation support, contact
[support@perkstar.co.uk](mailto:support@perkstar.co.uk) with the relevant
`X-Request-Id`, never a secret.

## Production review

* [ ] Data flow, role, purpose, and lawful basis are documented.
* [ ] Test data is separated from live credentials and jobs.
* [ ] Secrets are stored server-side and rotation is tested.
* [ ] Webhook verification, deduplication, and retention are tested.
* [ ] OAuth disconnect and refresh-token replay are handled.
* [ ] Customer export, correction, deletion, and suppression propagate.
* [ ] Logs redact secrets and unnecessary personal data.
* [ ] The DPA and sub-processor list have been reviewed.


## Related topics

- [Quickstart](/quickstart.md)
- [Build an OAuth marketplace app](/guides/oauth-marketplace.md)
- [Go-live checklist](/support/go-live-checklist.md)
- [Authentication and scopes](/fundamentals/authentication.md)
- [Connect with MCP](/tools/mcp.md)