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

## 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                    |
| `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 only the read scopes needed by its reconciliation job.

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


## Related topics

- [Auth check + org context](/api-reference/marketplace/auth-check-+-org-context.md)
- [List locations](/api-reference/locations/list-locations.md)
- [List customers](/api-reference/customers/list-customers.md)
- [Create or upsert a customer](/api-reference/customers/create-or-upsert-a-customer.md)
- [Send a wallet push](/api-reference/pushes/send-a-wallet-push.md)