Authentication

How API keys work

An API key belongs to one organization and acts as the person who created it. A request made with a key can do what its creator’s role allows, and only in the key’s organization; a request for any other organization returns 403. Keys start with pk_.

Creating a key

You need the Admin role or higher.

Open API keys

Go to Config → General → API Keys.

Create the key

Give the key a name that says what it’s for, such as “CI pipeline” or “SIEM export”, and optionally an expiry in days.

Copy it

The full key is shown once. Store it in a password manager or secrets manager.

Tierity keeps only a hash of the key, so it can’t show it to you again. If you lose it, revoke it and create a new one.

Using a key

Send the key in the Authorization header:

curl https://tierity.com/api/organizations/{orgId}/workbench/findings \
  -H "Authorization: Bearer pk_..."

const res = await fetch(`https://tierity.com/api/organizations/${orgId}/workbench/findings`, {
  headers: { Authorization: `Bearer ${process.env.TIERITY_API_KEY}` },
});
const { findings } = await res.json();

import os, requests

res = requests.get(
    f"https://tierity.com/api/organizations/{org_id}/workbench/findings",
    headers={"Authorization": f"Bearer {os.environ['TIERITY_API_KEY']}"},
)
findings = res.json()["findings"]

Managing keys

Config → General → API Keys lists every key with its status and when it was last used. Delete a key there and it stops working immediately; later requests with it return 401. You can also deactivate a key without deleting it by sending {"is_active": false} to PATCH /api/api-keys/{id}. On the Enterprise plan, enterprise admins can also see and revoke any member’s keys from Enterprise Config.

Rotating a key

There’s no in-place rotation:

Create a new key.
Switch your integration to it and check it works.
Delete the old key.

Good practice

Keep keys out of source control; use environment variables or a secrets manager.
Create a separate key for each integration, so you can revoke one without breaking the others.
Set an expiry on keys used for one-off jobs.
Delete keys whose last use is old.
Because a key acts as its creator, create keys from an account whose role is no higher than the job needs.

API Documentation

Core Endpoints

How API keys work

Creating a key

Using a key

Managing keys

Rotating a key

Good practice

​How API keys work

​Creating a key

​Using a key

​Managing keys

​Rotating a key

​Good practice

How API keys work

Creating a key

Using a key

Managing keys

Rotating a key

Good practice