Authenticating Your Requests

The Tenanted API authenticates a request with one header: Api-Key carries the key you created in the app. A key created in the app belongs to one organization, so it already knows which organization you are acting for. There is no /v1 prefix in the path, and an optional Api-Version header pins the release.

Before You Start

You need one value:

• An API key. Create one in the app: Creating and Managing API Keys.

You do not need an organization ID to get started. A key created in the app is issued against one organization, and a request that names no organization runs against that one.

The Headers

Every request goes to https://api.trykintsugi.com, with no version prefix in the path:

The default release never moves. A request without Api-Version runs against 2026-07-21, the launch release, today and after newer releases ship, so leaving the header out can never change an integration underneath you. Sending it anyway makes the release you built against explicit in your own code.

Choosing an Organization

If you send a selector, it has to name an organization your key can reach. Naming one it cannot reach returns 404 not_found, the same response as an organization that does not exist, so a key can never be used to probe which organizations exist.

When a credential reaches more than one organization, the selector is how you pick one:

• A write with no selector returns 400 missing_target_selector, because a create cannot mean "all of them".
• Selectors that point at different organizations return 400 conflicting_target_selectors.
• An Entity-Id that matches more than one connection returns 409 entity_resolution_ambiguous. Add Entity-Source or Connection-Id to settle it.

List organizations returns every organization your credential can access, which is where to read the ID from when you need one.

Endpoints That Take a Session Token

A small set of endpoints manage people and credentials rather than data, and they do not accept an organization API key:

• Users, such as List organization users and Invite a user to an organization, accept only a signed-in user's session token, sent as Authorization: Bearer <token>. An API key is rejected.
• API Keys, such as Create an API key, take a session token from an Owner or Admin. An organization API key gets 401 unauthorized, exactly as if no credential had been sent, and sending both an Api-Key and a bearer token returns 400 multiple_credentials.

A few public endpoints take no credential at all. The API Reference shows the credential each endpoint accepts.

Your First Request

Start with a read. GET /products/categories returns Kintsugi's product category catalog. It takes no parameters and no selector, and the catalog is the same for every caller, which makes it a clean way to prove your key works without creating anything:

curl https://api.trykintsugi.com/products/categories \
  -H "Api-Key: $KINTSUGI_API_KEY" \
  -H "Api-Version: 2026-07-21"

A 200 with a JSON body means your key is good and you are ready to build.

Once that works, every other data endpoint takes the same Api-Key header. 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

Every error comes back in the same envelope, and the code tells you where to look:

{
  "code": "unauthorized",
  "message": "Invalid API key.",
  "requestId": "req_8f3k2mNpQr7Ls",
  "errors": []
}

Branch on code, not on message: the message is written for people and can change. Quote the requestId when you contact support.

Error Handling covers the full set of status codes and error codes, field-level validation errors, and retry behavior.

Using an SDK Instead

The official SDKs and the Kintsugi MCP server use the v1 API, with its x-api-key and x-organization-id headers and /v1 paths. They do not cover the Tenanted API yet, so call the Tenanted API over HTTP as shown on this page.

Next Steps