Get API access
Use this to integrate an external system with ToucanTix through the GraphQL API, for example to create orders from a partner platform or read customer and order data. This article uses API terminology; the rest of the documentation describes the same concepts in product terms.
Before you start
Confirm:
- you know which account (tenant) the integration should act on
- an account admin can approve the integration and its scope
- your client can send HTTPS POST requests with custom headers
Request credentials
There is no self-service token page in the back office. API keys are issued by ToucanTix and are tied to a staff user, so the key inherits that user's role and permissions.
- Contact ToucanTix support and describe the integration: which account, which data you read or write, and the expected request volume.
- Ask support to issue an API key for a dedicated integration user rather than a personal account, so the key survives staff changes and its permissions can be scoped.
- Store the key in a secret manager. Anyone with the key can act with that user's permissions.
Shop-style flows are different: public offer discovery needs no user credentials, and cart mutations use the short-lived access token that the API returns when a cart is created or a customer logs in.
Authenticate requests
The API is GraphQL over HTTPS with a single endpoint per environment; support provides the endpoint URL and the API reference link for your platform. Every request needs:
- `Authorization: Bearer <token>` — your API key, or a short-lived token for shop flows. Public shop discovery queries work without this header.
- `X-Tenant-Domain` — the domain of the account or shop the request targets. Requests without a valid value are rejected with an error such as "HTTP header X-Tenant-Domain needs to reference a valid shop."
- `Accept-Language` (optional) — the locale for translated content.
Example first request:
```bash curl -X POST https://<api-endpoint>/graphql \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <your-api-key>" \ -H "X-Tenant-Domain: <your-shop-domain>" \ -d '{"query": "{ tenant { name } }"}' ```
A successful response returns the account name, which confirms that the token, the tenant header, and the endpoint fit together.
Explore the schema
The GraphQL schema is self-describing: with valid credentials you can use introspection, so GraphQL IDEs and code generators work against the live endpoint. ToucanTix also publishes a generated API reference with the schema types, example queries, and the typical shop flow (discover offers, build a cart, attach a customer, finalize, pay); ask support for the reference link if you do not have it.
For events flowing out of ToucanTix (for example settled orders or customer changes), use webhooks instead of polling; see Set up webhooks.
Usage boundaries
ToucanTix does not publish fixed rate limits. Keep request volume proportionate to real user activity, cache stable data such as offer listings, and agree on expected volume with support before launching high-frequency synchronization. Support can help with credentials, headers, and documented workflows; the integration code itself is owned by your team.
Expected result
You have an API key for a dedicated integration user, a verified endpoint and tenant domain, and a first successful GraphQL response.
Troubleshooting
| Problem | What to check |
|---|---|
| Response complains about the tenant header | `X-Tenant-Domain` is present and references a valid shop or account domain for your platform. |
| Requests are rejected as unauthorized | The `Authorization` header uses the `Bearer` scheme, the key is unchanged, and the linked user still exists and has the needed permissions. |
| A field returns null or is denied | The integration user's role; the API enforces the same permissions as the back office. |
| Introspection fails | Whether you are calling the correct endpoint for your platform with valid credentials. |
