Authentication

Every endpoint of the Wallet App API, apart from requesting a token, needs an API token. In this guide we look at how to get a token, how to send it and how abilities decide what a token may do.

The API uses bearer tokens. Basic authentication and query-string keys are not supported.

Request a token

Exchange the email and password of a dashboard user for a token with POST /oauth/token. In the same call you choose the abilities (also called scopes or permissions) the token gets, so request only what the integration needs.

curl -X POST https://api.walletapp.co/oauth/token \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "integration@example.com",
    "password": "<your_password>",
    "permissions": ["members.get", "members.store", "passes.get"]
  }'

The response contains the token in data.key. Store it like a password, for example in a secret manager or an environment variable. It is not shown again.

Send the token

Add the token to the Authorization header of every request:

curl https://api.walletapp.co/members/list?brand_id=<brand_id> \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <your_token>"

Always send Accept: application/json so errors come back as JSON.

Abilities

Each endpoint lists the ability it needs under Abilities, for example members.store. A token can only call endpoints for which it holds the ability, and only for the organizations of the user it was created for.

• A missing or invalid token returns 401.
• A valid token without the required ability returns 403.
• A token that has no access to the organization or brand in the request returns 401 or 404, depending on the endpoint. The two cases are deliberately not distinguishable.

Use GET /oauth/token to see the abilities of the token you are holding.

Rotate and revoke

Create a separate token per integration so you can revoke one without touching the others. To revoke a token, call DELETE /oauth/token with that token. If you suspect a token has leaked, revoke it and request a new one.

Limits and retries

Tokens are rate limited, and write calls can be retried safely with an Idempotency-Key header. See Limits and retries.