Create and Use API Keys in Kintsugi Portfolio

Step‑by‑step guide to creating and using API keys for integrations in Kintsugi Portfolio

Updated 5 seconds ago

Everything you can do in Kintsugi Portfolio you can also do through the Kintsugi APIs. This is how software companies and larger firms provision clients and pull compliance data into their own tools.

Where to Find the Documentation

Full endpoint reference, request and response examples, and changelog live at docs.trykintsugi.com. This help article covers only what you need to know before you start.

Two Kinds of API Key

When you create a key, you choose its scope. The scope decides which clients the key can reach.

Key scope	What it works on	Choose it when
Partner (all organizations)	Every client organization in your portfolio, through the Partner Management API	You need one key that reaches all of your clients
Organization	The main Kintsugi APIs for one client organization only	You only need access to a single client

If you are not sure, use the narrowest key that does the job. An organization key limits what could be affected if the key is ever exposed.

Create an API Key

You need the Owner or Admin role.

In your Kintsugi Portfolio, go to Settings.
Go to API Keys and click Create Key.
Complete the information required:
1. Under Key Scope, choose Organization or Partner (all organizations).
2. If you chose Organization, select the client under Organization.
3. Choose an Expiration. The default is Never.
4. Click Create.
Copy the key using the copy icon and store it somewhere secure, then click Done.

You can only see the full key once.

After you click Done, Kintsugi shows only the key ID, never the full key. If you lose it, delete the key and create a new one.

Manage Your Keys

The API Keys page lists your keys in two tables, one for each scope.

Element	What it shows
Partner Keys	Each partner key with its Key ID, Created date, and Expires date
Organization Keys	Each organization key with its Key ID, the client Organization and Org ID it belongs to, and its Created and Expires dates
Key ID	The first part of the key, so you can tell which key is which. It is not the full key and cannot be used to make requests.
Delete	Removes the key. Delete a key you no longer use, or any key that may have been shared by mistake, then create a new one.
Results per page	How many keys each table shows at once, 10 by default

Authentication

Item	Detail
Header	Send `X-API-KEY: your-key` on every request
Acting on one client with a partner key	Add `x-organization-id: orgn_...` to the request. You can find each client's Org ID in the Organization Keys table or on the client's overview.

What the Partner API Covers

Create, search, and update client organizations, including batch creation of up to 20 at once
Add bank details to a client organization
Invite portfolio users and assign them to clients
Create and track registrations and filings
Read nexus and monitoring data
Configure notification and billing settings at the portfolio level, with per-client overrides
Onboard referral partners

Before You Create Registrations

A live client organization must have bank details on file before the API will create a registration for it. Test organizations skip this check, so a request that succeeds against a test organization can fail against a live one with the message "Bank details are required before creating a registration." Attach bank details first using the bank details endpoint.

Good to Know

Treat API keys like passwords. Do not paste them into email, chat, tickets, or screenshots.
Set an expiration on keys you only need for a limited time, such as a one-off migration.
Test your integration against a test organization, then verify against a live organization before you go to production.

Need Help?

For further concerns, we're always here to help. If you can't find the answer you're looking for, just reach out to us using the chat in the bottom right corner of your screen.