> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tierity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Create API keys, use them as bearer tokens, and revoke them.

## 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](https://docs.tierity.com/concepts/roles-permissions.md) 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.

**1. Open API keys**

Go to **Config → General → API Keys**.

**2. 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.

**3. Copy it**

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

> [!WARNING]
>
> 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:

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

```javascript theme={null}
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();
```

```python theme={null}
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:

1. Create a new key.
2. Switch your integration to it and check it works.
3. 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.