---
title: "Authentication and readable scope | Trellus Call Data API"
description: "How to authenticate Trellus Call Data API requests: where to copy your API key, which header each host expects, and how the key inherits your permissions."
source: "https://www.trellus.ai/developers/api/authentication"
note: "Text-only copy of the page for AI assistants and agents. Link to the source address, not this file."
site_summary: "https://www.trellus.ai/llms.txt"
---

# Authentication and readable scope

Where to copy your key, which header each host expects, and what the key can read.

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

This documentation is public. Requests to customer data require authentication and retain your existing Trellus permissions. For an AI assistant that connects through browser sign-in, use the [MCP setup guide](https://www.trellus.ai/developers/mcp).

## Which header to send

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

Authentication header for each endpoint

| Endpoint | Headers |
| --- | --- |
| [Visible directory](https://www.trellus.ai/developers/api/visible) `ext.trellus.ai/visible` | `api_key: $TRELLUS_API_KEY` |
| [Bootstrap](https://www.trellus.ai/developers/api/bootstrap) `ext.trellus.ai/bootstrap` | `api_key: $TRELLUS_API_KEY` |
| [List calls and transcripts](https://www.trellus.ai/developers/api/list-calls) `rpt-2.trellus.ai/session-list-v6` | `Authorization: Bearer $TRELLUS_API_KEY` |
| [Count calls and sum durations](https://www.trellus.ai/developers/api/metrics) `rpt-2.trellus.ai/metric-details-v7` | `Authorization: Bearer $TRELLUS_API_KEY` |
| [Read one call](https://www.trellus.ai/developers/api/session) `rpt-2.trellus.ai/session` | `Authorization: Bearer $TRELLUS_API_KEY` and `x-session-id` |
| [Audio links](https://www.trellus.ai/developers/api/audio) `api.trellus.ai/get-audio-links` | `api_key: $TRELLUS_API_KEY` and `session_id` |

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

Verify readable users

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

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

```python
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](https://www.trellus.ai/developers/api/visible) 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](https://www.trellus.ai/developers/api/errors).