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

# API Keys

> Authenticate your API requests with a Pretectum API key

An integration authenticates its Pretectum API requests with an API key. A key is a long-lived
credential that you create in the Pretectum app and send on each request. There is no token to
exchange and no expiry to refresh against, so integrating is a single header. (A tool acting on a
signed-in person's behalf can send that user's access token in the same header instead; see
[Access Tokens](/api-reference#access-tokens).)

## Creating a key

Keys are managed in the Pretectum app under **Configuration → API Keys**. Creating one asks for:

| Field | Notes |
| - | - |
| **Name** | Required, and unique within your tenant. It identifies the key in audit records, so name it after the integration that will use it. |
| **Description** | Optional. |
| **Expires** | Optional. Leave it empty for a key that does not expire. |

<Warning>
  **The key is shown once, at the moment it is created.** Pretectum stores only a hash of it and
  cannot show it to you again. Copy it before closing the dialog. If you lose it, delete the key and
  create another.
</Warning>

Afterwards the list shows a masked form, such as `pre_Ab3d********Xy9z`, which is enough to tell your
keys apart but not to authenticate with.

### What a key looks like

```
pre_Ab3dEf5gHi7jKl9mNo1pQr3sTu5vWx7yZa9bCd1e
```

Every key starts with the `pre_` prefix followed by 40 alphanumeric characters. The prefix makes keys
easy to spot in logs and in secret scanners.

## Using a key

Send the key in the `Authorization` header:

```bash theme={null}
Authorization: pre_your_api_key
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.pretectum.io/v1/my/businessareas" \
    -H "Authorization: pre_your_api_key" \
    -H "Accept: application/json"
  ```

  ```javascript JavaScript theme={null}
  const apiKey = process.env.PRETECTUM_API_KEY;

  const response = await fetch('https://api.pretectum.io/v1/my/businessareas', {
    headers: {
      'Authorization': apiKey,
      'Accept': 'application/json'
    }
  });
  ```

  ```python Python theme={null}
  import os
  import requests

  api_key = os.environ['PRETECTUM_API_KEY']

  response = requests.get(
      'https://api.pretectum.io/v1/my/businessareas',
      headers={
          'Authorization': api_key,
          'Accept': 'application/json'
      }
  )
  ```
</CodeGroup>

## What a key can do

A key carries no permissions of its own. It is granted access the same way a person is:

1. **Roles** decide which resources the key may act on, and which of view, add, edit and delete it
   may perform on each.
2. **Business areas** decide which data the key may reach. A key with no business area assignment
   sees nothing, whatever its roles say.

Both are managed in the Pretectum app by your tenant administrator. Changes take effect on the next
request; there is no token to expire first.

## Managing keys

You can create as many keys as you need, and it is worth using one per integration rather than
sharing a single key. Each key records its own last-used timestamp, so a key that stops being used is
easy to spot and safe to delete.

A key can be:

| Status | Meaning |
| - | - |
| **Active** | Usable. |
| **Inactive** | Switched off without being deleted. Requests are rejected until it is switched back on. |
| **Expired** | Past its expiry date. Requests are rejected. |

Deleting a key takes effect immediately.

## Error responses

| Status | Description |
| - | - |
| `401 Unauthorized` | The key is missing, malformed, unknown, inactive, expired or deleted. All of these are reported the same way, so a caller cannot probe for which. |
| `403 Forbidden` | The key is valid, but it lacks the role permission or the business area access the request needs. |

```json theme={null}
{
  "message": "Unauthorized"
}
```

<Tip>
  A `401` means the credential itself was rejected; check the key, or sign in again if you sent a
  token. A `403` means the credential is fine but its access is not; ask your tenant administrator
  about roles and business areas.
</Tip>

## Keeping keys safe

* Store keys in a secret manager or an environment variable, never in source control.
* Never put a key in client-side code, a browser request, or a URL query string. Anyone who reads it
  can act as your integration.
* Rotate by creating the replacement first, moving traffic to it, then deleting the old key. Keys are
  independent, so there is no window where neither works.
* Delete keys you no longer use.