Authentication and readable scope

Your API key

Use the API key belonging to your Trellus user. In Trellus, open Settings → Integrations → API (the Call Data API page) to copy your own key. Keep it in a server-side environment variable named TRELLUS_API_KEY.

The key inherits the user’s existing permissions. It is not a separately restricted read-only credential. Verify the readable users with /visible; team_id never grants access.

Do not place API keys in browser code, query strings, analytics, logs, public repositories or prompts. Contact support to replace an exposed key.

Which header to send

The hosts do not share one header. Send the key the way each endpoint expects it.

Check what the key can read

Call /visible first. A 200 response proves the key works and shows the users readable in the requested team.

curl https://ext.trellus.ai/visible \
  -H "api_key: $TRELLUS_API_KEY"

const response = await fetch("https://ext.trellus.ai/visible", {
  method: "GET",
  headers: {
    "api_key": process.env.TRELLUS_API_KEY,
  },
});
console.log(await response.text());

import os
import requests

response = requests.get(
    "https://ext.trellus.ai/visible",
    headers={
        "api_key": os.environ["TRELLUS_API_KEY"],
    },
)
print(response.text)

See Visible directory for the response.

Access problems

401 “not permissioned” or “not authorized”

The user behind the key cannot read that session or team. Check /visible and ask your team admin to review reporting access. A team_id parameter does not grant access. “inactive user” can also mean the key is invalid or the account is inactive.

I need a team-wide read-only key, or my key was exposed

A Trellus API key belongs to a user and inherits their permissions; using it for reporting does not make it a separately restricted credential. Each user can copy their own key in Settings → Integrations → API. Use an appropriately permissioned account for team reporting, verify /visible, and contact support for key replacement if it was exposed.

Other responses are covered in Errors and troubleshooting.