Authentication

The Bearer token

Send the token in the Authorization header on every request. Tokens never go in the URL. All traffic is HTTPS.

curl -G "https://www.membber.com/api/v1/customers" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  --data-urlencode "store_id=<store-id>"

A missing or invalid token returns 401 UNAUTHENTICATED. A valid token without the operation's scope returns 403 FORBIDDEN. Both use the standard error envelope.

Where tokens come from today

The API's production consumers are Membber's own apps, plus merchant-issued agent keys. There are three credentials:

• Customer sessions. A member signs in on the Membber iOS app or App Clip and the app holds a Membber session token. It is sent as a Bearer token and carries the customer:* scopes for that member.
• Business sessions. An owner or staff member signs in on the Membber Place app and the app holds a staff session token, always sent as a Bearer token. It carries merchant:* scopes, and front-desk actions additionally check that person's staff:* permissions. Every merchant call is scoped to a single store.
• Agent keys. Scoped machine keys a merchant issues for their own store, built for AI agents and automations. See below.

Agent keys

Agent keys let a merchant hand a tightly-scoped credential to an AI agent or automation without sharing their login. They are issued in the Membber Place app, and they are deliberately conservative:

• Format: mbr_live_... or mbr_test_.... The full key is shown once at creation and can never be retrieved again; only a salted hash is stored.
• Each key is bound to the store that issued it. It can never read or write another store, whatever parameters it sends.
• Grantable scopes today: merchant:read, staff:approve and staff:redeem.
• Keys work on a deny-by-default allowlist of operations, currently: reading loyalty state, listing and searching customers, granting and undoing stamps, and advancing order fulfilment. Money operations such as refunds are deliberately excluded.
• Keys can be revoked at any time and can carry an expiry.

# Agent keys look like this (issued once, never retrievable again):
# mbr_live_9f2c41d8a06b73e5_...64 hex characters...

curl -G "https://www.membber.com/api/v1/loyalty/state" \
  -H "Authorization: Bearer $MEMBBER_AGENT_KEY" \
  --data-urlencode "customer_id=<customer-id>"

Scopes

Scopes follow an audience:action shape. Each operation in the reference shows its scope next to the method and path.