Skip to main content
Perkstar accepts a bearer credential in the Authorization header:
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

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

​
Available direct-key scopes

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.
Never send an API key to a browser or expose it in a public Odoo client action. Calls must originate from trusted server code.
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 contextList locationsList customersCreate or upsert a customerSend a wallet push