Creating and Managing API Keys
Every Tenanted API request to a data endpoint carries an API key in the Api-Key header. This page covers creating a key in the app, the one moment you can copy it, and how to manage keys after that, in the app or through the API Keys endpoints.
Four clicks in the Configuration page.
The key is shown once and never again.
Send your key and confirm it works.
Every endpoint your key can reach.
Before You Start
You need an account on the Kintsugi platform and access to an organization.
API keys need a paid plan that includes them. If the API Keys tab asks you to upgrade, the organization you are signed in to does not include them yet, so check which organization you are in before you start.
A key created in the app is scoped to one organization and acts on that organization, so a request made with it needs no organization header. You can hold several keys at once, which is what makes rotation possible without downtime.
Create an API Key
Open the API Keys Tab
Sign in to the Kintsugi platform. If you do not have an account yet, sign up first.
Select Configuration in the left sidebar, below Tools.
Configuration opens on a row of tabs. Select API Keys.
The tab lists every key belonging to the organization you are signed in to, with a search box, a link back to this documentation, and a New button. A new organization has none yet.
Create a New API Key
Click New. The New Organization API Key dialog opens, named for the scope the key will have.
Choose when the key should expire: Never, One Month, Six Month, or One Year.
Pick the shortest window that covers the work. An expiring key limits how long a leaked one is useful, and the expiry date is the reminder to rotate. One Month suits local development and spikes, One Year suits a production integration you will rotate on schedule, and Never is worth choosing only when something other than the calendar will retire the key.
Confirm to generate the key.
Copy and Secure Your API Key
This is the only time the key is visible. Copy it before you close the dialog. There is no way to reveal it again, so a key you did not copy has to be deleted and replaced.
Click the copy icon, or Manually copy API key to select the full value yourself.
Paste it straight into wherever your application reads secrets from, before you do anything else.
Click Done.
Three habits worth keeping from the start:
- Read the key from the environment, never from source. A key in a commit is a key in your history, and rewriting history is a worse afternoon than rotating a key.
- Use a separate key per application and environment. Keys are independent, so one can be revoked without taking the others down with it.
- Share through a password manager, not chat or email.
Viewing and Managing Your API Keys
The API Keys tab lists each key with its truncated value under KEY, plus its CREATED and EXPIRES dates. Only the truncated form is ever shown again. Use the search box to find a key, and the three-dot menu (⋮) at the end of its row to delete it.
Deleting a key takes effect immediately and cannot be undone. Anything still using it starts getting 401 unauthorized on the next call, so put the replacement in place first. See Error Handling for what an authentication failure looks like.
Managing Keys Through the API
The Tenanted API exposes the same lifecycle as four endpoints. They manage credentials, so they do not accept an organization API key: they take the session token of a signed-in Owner or Admin, sent as Authorization: Bearer <token>, with Organization-Id naming the organization whose keys you are managing. An organization API key gets 401 unauthorized, and a request that sends both an Api-Key and a bearer token gets 400 multiple_credentials.
| Endpoint | What it does |
|---|---|
GET /api-keys | Lists the organization's keys. active=false lists archived keys instead of current ones. Pages forward with limit (1 to 100, default 50) and cursor. |
POST /api-keys | Creates a key and returns its secret token, once. |
PATCH /api-keys/{api_key_id} | Changes a key's expiresAt, or removes the expiry with null. |
DELETE /api-keys/{api_key_id} | Revokes a key. |
Creating a key takes one optional field. expiresAt is an RFC 3339 UTC timestamp ending in Z, and it has to be in the future; leave it out for a key that does not expire.
A 201 Created returns the key's id and its token:
{
"id": "3f6c2b1e-8a4d-4c2e-9b1f-2d7e5a6c9f10",
"token": "tok_2mNpQr7Ls8f3k"
}The token is returned here and never again. Listing keys returns their metadata (id, scope, organizationId, createdAt, expiresAt), never the secret, so store the token before you do anything else.
A few rules worth knowing:
- Updating sends
expiresAtwith a new future timestamp, ornullto remove the expiry. An empty body returns400 invalid_request, since it asks for no change. A successful update returns204 No Content. - Revoking returns
204 No Content. A key you cannot revoke, including one that does not exist, returns404 not_found. - A signed-in user without the Owner or Admin role gets
403 forbidden.
Rotating a Key
Because an organization can hold several keys at once, rotation needs no downtime and no maintenance window:
Generate a new key alongside the one you are retiring, in the app or with Create an API key.
Update the secret your application reads and roll it out.
Make a request and check it succeeds. Making an Authenticated Request is the quickest check.
Only once nothing is using it. Deleting first is what turns a rotation into an outage.
Set expiry when you create the key and rotation stops being something you have to remember. The EXPIRES column is your schedule, and expiresAt on List API keys is the same date for your own tooling.
Next Steps
Send Api-Key, and learn when to add an organization selector.
Choose how you will integrate before you write code.
Python, TypeScript, Java, PHP, and Ruby clients for the v1 API.
Run each workflow interactively before you build it.
Status codes, error codes, and what a rejected key returns.
Give your AI coding assistant the v1 API and docs.