Authentication
Every request to the TapTree API is authenticated with a Bearer token. TapTree offers two API key families that target different integration shapes — pick the one that fits, or use both side-by-side.
Pick your key family
| Fine-grained API keys | Classic acceptor keys | |
|---|---|---|
| Scope | Organization + environment + explicit permission scopes | Single payment acceptor |
| Format | Starts with tt_live_ or tt_sbx_; rest is opaque | Opaque token, test_ prefix in sandbox |
| Endpoints | Webhook Endpoints, Payments, Refunds, Chargebacks, Settlements, Acceptors, Impact | Payments, Refunds, Chargebacks, Settlements, Acceptors, Impact |
| Rotation | Self-service in the dashboard; dual-control force-rotate available | Self-service in the dashboard, per acceptor |
| Audit log | Per-request, by key_id | Per-acceptor |
Both families are first-class. New integrations should default to fine-grained API keys because they have explicit scopes, dual-control rotation, and per-request audit-trail integration. Use classic acceptor keys when you want one key per sales channel scoped to a single acceptor.
Fine-grained API keys
Recommended for new integrations. Fine-grained API keys carry explicit scopes, are independent of payment-acceptor boundaries, and surface every authenticated action in the dashboard's audit log.
Manage your fine-grained API keys at Developers → API keys in the dashboard.
Key format
Fine-grained API keys start with tt_live_ (production) or tt_sbx_ (sandbox). The remainder is opaque — treat the entire string as the credential and never split, normalize, or truncate it.
Examples
tt_live_… # production
tt_sbx_… # sandbox
A short checksum is embedded so that an obviously malformed key (typo, copy-paste truncation) is rejected at the edge without consuming a rate-limit slot. Validate keys by attempting an API call — there is no separate format-check endpoint.
Never expose API keys client-side. A pri key acts on behalf of
your whole organization within its declared scopes. If you suspect one
was leaked, rotate it in the dashboard immediately — every request the
key has signed is recorded in the audit log so you can audit blast
radius. TapTree never sends a key over email; rotation is the only way
to obtain a new secret.
Scopes
Every fine-grained API key carries an explicit list of resource:action permissions. The server enforces each scope at request time: a key without webhooks:update cannot update a webhook endpoint, even via a different route.
Enforced scopes:
| Resource | Actions |
|---|---|
payments | create, read, update, capture, cancel |
refunds | create, read |
chargebacks | read |
settlements | read |
webhooks | read, create, update, delete, rotate_secret |
acceptors | read |
impact | read |
Tick exactly the scopes your integration calls and nothing else.
Acceptor binding
Fine-grained keys may be bound to a specific acceptor at mint time. Transaction-resource scopes (payments, refunds, chargebacks, settlements, acceptors, impact) require an acceptor-bound key — they query data scoped to the bound acceptor. Organization-level keys (no acceptor binding) are usable for webhooks only.
Environment binding
live keys see and mutate live data; sbx keys are confined to the matching sandbox environment. There is no env query parameter and no fallback — the environment is server-bound at mint time. If you need both, mint one key per environment.
Creating a key
- Open Developers → API keys in the dashboard.
- Click Create API key and pick the environment (
liveorsbx). - Tick the scopes the key needs. Optionally bind the key to a single acceptor.
- The plaintext key is shown exactly once in the drawer. Copy it immediately and store it in your secret manager — the key is HMAC-hashed at rest and cannot be shown again.
Using a fine-grained API key
List your webhook endpoints (live)
curl https://api.taptree.org/v1/webhooks \
-H "Authorization: Bearer tt_live_pri_AbCd1234EfGh5678IjKl9012MnOp3456_AB12CD"
Same call against the sandbox
curl https://api.taptree.org/v1/webhooks \
-H "Authorization: Bearer tt_sbx_pri_AbCd1234EfGh5678IjKl9012MnOp3456_AB12CD"
Force-rotation (dual-control)
For incidents where a key may have been compromised, the dashboard offers a force-rotate workflow that requires a second authorized member of your organization to co-sign the rotation. This prevents a single compromised dashboard session from quietly issuing a replacement key.
Force-rotation invalidates the old key immediately. Have your replacement secret deployed before kicking off the workflow.
Classic acceptor keys
Classic acceptor keys authenticate requests for a single payment acceptor — the sales-channel-level entity (webshop, POS terminal, mobile checkout) you've configured in your TapTree organization. They predate the fine-grained API key family above and remain the auth method for the classic transaction endpoints.
When to use a classic acceptor key
Use a classic acceptor key when you want a single-acceptor-scoped credential for any of the classic transaction endpoints:
/v1/payments/v1/refunds/v1/chargebacks/v1/settlements/v1/acceptor(single-acceptor read)/v1/impact
For Webhook Endpoints, use a fine-grained API key instead.
Test vs live keys
Each acceptor has a dedicated live key for production traffic and a test key for sandbox traffic. The test-mode marker is part of the key itself; you never need to flip a separate flag on the request.
Read the current acceptor (live)
curl https://api.taptree.org/v1/acceptor \
-H "Authorization: Bearer <your-live-acceptor-key>"
Read the current acceptor (test)
curl https://api.taptree.org/v1/acceptor \
-H "Authorization: Bearer test_<your-acceptor-key>"
Managing classic acceptor keys
Access and rotate classic acceptor keys in Dashboard → Acceptors → <your acceptor> → Tokens. Each key is shown once at issuance; rotate to retire a compromised secret. TapTree never sends a key over email.
Keep classic acceptor keys server-side only. Don't ship them to a browser or mobile client — anyone who can read the bytes can act as that acceptor. Browser-side payment collection is built on the TapTree SDK, which never exposes a long-lived API key to the customer device.
Scope
An acceptor token authorizes actions for one acceptor only. It cannot read other acceptors in the same organization or manage webhook endpoints. Cross-acceptor or organization-wide operations always require a fine-grained API key.
Enforce HTTPS
All requests must use HTTPS. Plain HTTP requests are rejected at the edge regardless of the Bearer token. This applies to both API keys and acceptor tokens.