Authentication

Every request to the TRUED API carries an API key. A key belongs to one TRUED workspace and only ever sees that workspace's data.

Create a key

1. In TRUED, open Settings, then Integrations, then API keys.
2. Choose Create key, give it a name you will recognise later (for example "Power BI dashboard"), and tick the permissions it needs. See Permissions.
3. Copy the key. TRUED shows it once. TRUED keeps only a fingerprint of the key, so nobody, including TRUED, can show it to you again. If you lose it, rotate the key.

Finance admins and workspace admins can create keys. TRUED emails your finance team whenever a key is created or rotated, so a new key never appears unnoticed.

Send the key

Send it in the Authorization header as a bearer token:

curl https://api.trued.io/v1/me \
  -H "Authorization: Bearer $TRUED_API_KEY"

/v1/me tells you which workspace the key belongs to and which permissions it has. It is the quickest way to check a key works.

Rules that keep your data safe:

• Never put a key in a URL. A request with a key in the query string is refused with 400, because addresses end up in logs and browser history.
• Never put a key in browser or mobile app code. The API is for server to server use. It sends no CORS headers, so a browser cannot call it directly.
• Keep the key in your platform's secret store, not in source code.

When a key is refused

A missing key, a mistyped key, a revoked key and an expired key all get the same answer:

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

TRUED does not say which of those it was, so someone guessing keys learns nothing. Check the key in Settings, Integrations, API keys: its status shows whether it is active, expiring or revoked.

Too many refused requests from one address in a minute are slowed down with 429.

Rotate a key

Rotate a key when someone who knew it leaves, or on a regular schedule.

1. Open the key and choose Rotate.
2. Choose how long the old key keeps working: stop now, 1 hour, 24 hours or 7 days.
3. Copy the new key (shown once) and put it in your system.
4. When your system is using the new key, choose Stop it now on the old one, or let it run out on its own.

While both keys work, each key's recent requests show which one your system is still using.

Revoke a key

Choose Revoke on the key. It stops working immediately, on the very next request. To connect again, create a new key.

Expiry

You can give a key an expiry date when you create it. After that date it is refused like any other key that is not valid. A key with an expiry date shows how long it has left in API keys.

What TRUED records

Every request is recorded for 90 days: the key, the address it came from, the path and the filters used, the status, the number of rows returned and how long it took. You can see a key's recent requests by opening it in API keys. TRUED never records the key itself.