API Keys

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.)

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.

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.

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:

Authorization: pre_your_api_key

curl -X GET "https://api.pretectum.io/v1/my/businessareas" \
  -H "Authorization: pre_your_api_key" \
  -H "Accept: application/json"

const apiKey = process.env.PRETECTUM_API_KEY;

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

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'
    }
)

What a key can do

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

Roles decide which resources the key may act on, and which of view, add, edit and delete it may perform on each.
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.

{
  "message": "Unauthorized"
}

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.

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.

Overview

Authentication

Business Areas

Schemas

Datasets

Data Objects

Creating a key

What a key looks like

Using a key

What a key can do

Managing keys

Error responses

Keeping keys safe

​Creating a key

​What a key looks like

​Using a key

​What a key can do

​Managing keys

​Error responses

​Keeping keys safe

Creating a key

What a key looks like

Using a key

What a key can do

Managing keys

Error responses

Keeping keys safe