Using the Twin API: organization and personal API keys

An API key lets a script or another system call Twin directly. This article covers the two kinds of key, how to create and revoke one, and how to authenticate a request.

Where API keys live

1. Click your name at the bottom of the left sidebar.
2. Select Organization.
3. Open the API Keys tab.

Each key gets a card showing its name, the last four characters of the key, and when it was last used. A personal key also says Personal key · acts as and the name of its owner. Only an Organization Owner can open the organization pages, so creating and revoking keys is limited to that role.

Organization keys and personal keys

The Type you pick when you create a key decides what it can reach.

• An Organization key belongs to the organization it was created in and reaches only that organization's data. It is not tied to a person, so it keeps working when the colleague who made it leaves.
• A Personal key is bound to your own account and acts as you. It carries your permissions in every organization you are a member of, and those permissions are read fresh on every call, so a change to your access applies to the key immediately.

Twin warns that a personal key bypasses the regular sign-in, including MFA, so treat it like your password. Use an organization key for anything that runs on behalf of the firm, and keep personal keys for your own scripts.

A personal key can only be created while you are signed in. An existing API key cannot create one.

Create a key

1. Click New key.
2. Under Type, choose Organization or Personal.
3. Give the key a name under Name (optional). It is optional, but a key without one shows up as Unnamed key.
4. Click Create key.

Twin then shows the key once, under Copy your API key: This is the only time the key is shown. Copy it now and store it somewhere safe: we keep only a hash of it, so it cannot be shown again. If you lose it, delete the key and create a new one. Use the copy button next to the key, put it in your password manager or secret store, then click Done.

Authenticate a request

Twin's API lives at https://api.twinai.nl and every endpoint sits under /v1. Send the key as a bearer token in the Authorization header:

curl https://api.twinai.nl/v1/user/me \
  -H "Authorization: Bearer YOUR_API_KEY"

That call is a good first test: it answers with the account the key acts as and the organizations it can reach. A request without a valid key is answered with 401 Unauthorized.

Revoke a key

Click the red trash icon on the key's card and confirm in the Delete API key dialog. The key stops working at once, so replace it in whatever uses it first. A lost key cannot be recovered: revoke it and create a new one.

Where the full reference is

The endpoint reference is served by the API itself, at https://api.twinai.nl/api. It lists every endpoint with its parameters and response, and you can try a call from the page after pasting a key into Authorize. The machine-readable version, which most client generators read directly, is at https://api.twinai.nl/api-json.

Good to know: changes to the API contract are announced to the organizations using a key before they reach production. If something you built stops working after a release, ask support@twinai.nl.