Authenticating Your Requests
Kintsugi authenticates every request with two headers: x-api-key identifies you, and x-organization-id says which organization you are acting for. There is no bearer token, no OAuth flow, and no session to keep alive.
What each one is, and where to get it.
One call that verifies your credentials without changing anything.
What 401, 403, and 405 are each telling you.
Every endpoint, with a ready-made request for each.
Before You Start
You need two values:
- An API key. Create one in the app: Creating and Managing API Keys.
- Your organization ID. Sign in to the Kintsugi platform and look at the organization switcher in the lower left of the sidebar, below your name.
The Two Headers
Every request goes to https://api.trykintsugi.com and carries both:
| Header | What it is | Example |
|---|---|---|
x-api-key | The key you created in the app. Identifies the caller. | 02f51ad8c56fde0f82702e08c8546257… |
x-organization-id | Which organization the request acts on. | org_12345 |
A key is issued against one organization and only works with that organization's ID, so the two values travel together. Sending one without the other fails.
HTTP header names are case-insensitive, so x-api-key and X-API-KEY are the same header. The API Reference shows the uppercase form and the examples here use lowercase; either is fine, and it is worth picking one and staying with it.
These headers belong on your server, never in a browser or a mobile app. Anything shipped to a client is readable by whoever holds it, and a leaked key can act on your whole organization. Call Kintsugi from your backend and let your own frontend talk to that.
Your First Request
Start with a read. GET /v1/products/categories returns Kintsugi's product category catalog, takes no parameters, and works on an organization with no data in it yet, which makes it a clean way to prove your credentials without creating anything:
curl https://api.trykintsugi.com/v1/products/categories \
-H "x-api-key: $KINTSUGI_API_KEY" \
-H "x-organization-id: $KINTSUGI_ORG_ID"A 200 with a JSON body means both headers are good and you are ready to build.
Read the key from the environment, as above, rather than pasting it into the command. That keeps it out of your shell history as well as out of your source. See Get product categories for the response shape.
Once that works, every other endpoint takes the same two headers. The API Reference carries a ready-made request for each one, and the API Lab runs whole workflows interactively so you can see the sequence before you write it.
When a Request Is Rejected
Authentication failures are specific, and which code comes back tells you where to look:
| Code | What went wrong | Where to look |
|---|---|---|
401 Unauthorized | The key was missing, misspelled, expired, or deleted. | Check the header name, then the EXPIRES column on the API Keys tab. |
403 Forbidden | The key is valid but not for that organization. | x-organization-id has to be the organization the key was created in. |
405 Method Not Allowed | Your credentials were fine; the verb was wrong. | Check the method in the reference. POST /v1/tax/estimate, for example, rejects a GET. |
Error Handling covers the full set of status codes, the error response body, and retry behavior.
Using an SDK Instead
The official SDKs take the key and organization ID once when you construct the client and set both headers on every call, so there is nothing per-request to remember:
Install a client and make your first authenticated call.
Python, TypeScript, Java, PHP, and Ruby.
Point your AI coding assistant at the live API and docs.
Next Steps
Choose transaction sync (L1) or the tax engine (L2) before you write code.
The endpoint most integrations reach for first.
Record completed sales, which is what nexus is derived from.
Run each workflow interactively before you build it.
Status codes, retries, and idempotency.
Swap a key with no downtime.