Account API tokens
Account API tokens let an application act on behalf of one ValueMapper account. They are intended for integrations, automations, and other software that calls the ValueMapper GraphQL API.
An account token identifies the account, not a team member or wallet user. Send it in the x-api-token header:
x-api-token: <account-token>
Use an admin JWT when a person is working in the ValueMapper account site. It has its own identity and access rules.
Choose a scope
The scope controls whether a custom account token can use operations marked as server-only in the GraphQL schema.
| Scope | Intended location | Access | Typical uses |
|---|---|---|---|
| Server | A trusted backend, worker, or secret manager | Account queries plus privileged operations marked @serverOnly | Creating or updating promotions, contacts, credit, redemptions, webhooks, merchants, and connected services |
| Client | A browser or distributed app where lower privilege is required | Client-safe account operations; server-only operations return 403 Forbidden | Read-only account experiences that do not need privileged mutations |
Choose Server only when the workload needs to change account data or perform another server-only operation. A server token is a secret: never include it in browser code, a mobile binary, source control, logs, screenshots, or support messages.
A client token has less authority, but it still identifies the account. Anyone who can inspect a distributed app can copy an embedded token, so expose one only when its available data is suitable for that audience. Client scope is not user authentication and does not make private account data public-safe.
What the scope check means
ValueMapper marks privileged GraphQL fields with the @serverOnly directive. When a custom token calls one of those
fields:
- a Server token is allowed to continue;
- a Client token is rejected with
403 Forbidden; - a missing or invalid token is rejected with
401 Unauthorized.
The scope is an access boundary, not a separate API. Both token types use the same GraphQL endpoint and
x-api-token header. Check the GraphQL reference for @serverOnly when deciding which scope an integration needs.
Create and store a token
Only account Owners can manage account API tokens.
- Open Account settings and find API tokens.
- Select Create token.
- Give the token a name that identifies its workload and environment.
- Choose Client or Server using the least privilege the workload needs.
- Copy the token when it is shown and store it in an appropriate secret manager or deployment environment.
Use a separate token for each workload and environment. This makes activity easier to identify and lets you revoke one integration without interrupting another.
Rotate or revoke a token
Account tokens do not expire automatically. Revoke a token when a workload is retired, the token may have been exposed, or its access is no longer required.
To rotate a token without interrupting a service:
- Create a replacement with the required scope.
- Update the consuming workload and confirm it can call ValueMapper.
- Revoke the old token from Account settings.
Changing scope requires creating a replacement token and revoking the old one.