Authentication

Every API request is authenticated with an API key sent in the Authorization header.

Create an API key

You need to be an admin in your organization to create or revoke API keys.

1. In the Safety Radar dashboard, open Settings.
2. Under Account, select API Keys.
3. Select New API Key.
4. Enter a Name that says what the key is for, for example HR system sync, and select Create.
5. On the new key, select Copy and store the key in your integration’s secret store.

What a key can do

• A key has admin access to your organization’s data through the API. Treat it like a password.
• Changes made through the API are attributed to the person who created the key.
• Keys do not expire. A key works until it is revoked.
• A key works for one organization only.

Send the key with each request

Put the key in the Authorization header with the Bearer scheme:

Authorization: Bearer YOUR_API_KEY

curl

curl https://safe-api.safetyradar.com/v2/events?limit=10 \
  --header "Authorization: Bearer $SAFETY_RADAR_API_KEY"

JavaScript

const response = await fetch('https://safe-api.safetyradar.com/v2/events?limit=10', {
  headers: { Authorization: `Bearer ${process.env.SAFETY_RADAR_API_KEY}` },
});
const { data } = await response.json();

Python

import os
import requests

response = requests.get(
    "https://safe-api.safetyradar.com/v2/events",
    params={"limit": 10},
    headers={"Authorization": f"Bearer {os.environ['SAFETY_RADAR_API_KEY']}"},
)
data = response.json()["data"]

When authentication fails

A missing, malformed, unknown or revoked key returns 401 Unauthorized:

{
  "code": "unauthorized",
  "message": "Invalid API token"
}

The message tells you which case it is: Missing authorization header, Invalid authorization header format, or Invalid API token.

Keep keys safe

• Store keys as secrets. Use your platform’s secret manager or environment variables. Never commit a key to source control or put it in client-side code such as a browser or mobile app.
• Use one key per integration. Name each key after the system that uses it, so you can revoke one integration without breaking the others.
• Rotate keys. To replace a key, create a new one, deploy it to your integration, then revoke the old one.
• Revoke keys you no longer need. On the API Keys page, select Revoke on the key and confirm. Requests with that key fail with 401 straight away.
• Review keys when people leave. Changes made with a key are attributed to the person who created it. When that person leaves, replace their keys with ones created by a current admin, and revoke the old keys.

The X-Team header (legacy)

Earlier integrations sent an X-Team header to choose a team. The API is now scoped to the whole organization, so the header is no longer needed and is ignored. Existing integrations that still send it keep working. New integrations should not send it.