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

# Authentication and scopes

> Protect API credentials and grant only the permissions an integration needs.

Perkstar accepts a bearer credential in the `Authorization` header:

```http theme={null}
Authorization: Bearer pk_live_...
```

Direct integrations use an API key. Marketplace applications use OAuth access
tokens beginning with `perk_at_`. Both credential types use the same endpoint
shapes and error format.

<Note>
  The public [Perkstar app for Zapier](/integrations/zapier) uses Perkstar
  OAuth. Users approve the hosted consent screen and never copy a raw Perkstar
  API key into a Zap field.
</Note>

## API key environments

| Prefix | Intended use | Live-data writes |
| - | - | - |
| `pk_test_` | Development and certification | Only isolated test transactions and simulated pushes |
| `pk_live_` | Production traffic | Allowed when the key has the required scope |

The environment is part of the signed secret. Renaming or rotating a key does
not change its environment.

## Available direct-key scopes

| Scope | Allows |
| - | - |
| `CUSTOMERS_READ` | Find and list customers |
| `CUSTOMERS_WRITE` | Create, update, or anonymise customers |
| `ENROLLMENTS_READ` | Read loyalty enrolments and balances |
| `ENROLLMENTS_WRITE` | Create or update enrolments |
| `TRANSACTIONS_READ` | Read live or test ledger rows |
| `TRANSACTIONS_WRITE` | Post stamps, redeems, and adjustments |
| `CARDS_READ` | Read card configuration |
| `EVENTS_READ` | Read the recent loyalty-event feed |
| `WEBHOOKS_READ` | Inspect webhook endpoints |
| `WEBHOOKS_WRITE` | Create, edit, or remove webhook endpoints |
| `LOCATIONS_READ` | Map Perkstar locations to external systems |
| `PUSHES_WRITE` | Send or simulate a wallet push |
| `MARKETPLACE` | Use the POS-friendly marketplace endpoints |

Test keys cannot be granted `CUSTOMERS_WRITE`, `ENROLLMENTS_WRITE`, or
`WEBHOOKS_WRITE`. The `MCP` permission is internal to OAuth consent and is never
available to direct API keys.

## Least-privilege examples

* **Read-only reporting:** customers read, enrolments read, transactions read, cards read.
* **POS till:** marketplace and locations read.
* **CRM sync:** customers read/write and enrolments read/write.
* **Wallet messaging:** customers read, enrolments read, pushes write.
* **Webhook consumer setup:** webhooks read/write; add events read only when it needs the recent-event feed.

## Credential handling

1. Keep keys in an encrypted server-side secret store.
2. Use separate keys for each integration and environment.
3. Give each key a name that identifies its owner and purpose.
4. Set an expiry where the integration can rotate automatically.
5. Rotate immediately after accidental exposure or team-member departure.
6. Revoke unused keys rather than leaving them dormant.

<Warning>
  Never send an API key to a browser or expose it in a public Odoo client
  action. Calls must originate from trusted server code.
</Warning>

The hosted API request builder is for short-lived testing with a test key on a
trusted device. Do not enter a live key on a shared computer, and never copy its
browser-based request pattern into a customer-facing application.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.