Skip to main content
TroopyDocs
GuidesSet up and use TroopyAppsConnect your servicesAPIThe API, the CLI and MCPChangelogEach update to Troopy

Developers

Account

Troop

Skills

Tasks and projects

Needs you

Routines and triggers

Brain

Docs

Canvas

Email

CRM

Outreach

Customers

Analytics

Sessions

Surveys

Support Agent

Tests and incidents

Disputes

Apps

Vault

Computer

Open Troopy
Troopy

Authentication

View as MarkdownOpen the page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

How a key acts as you in one workspace, how scopes and roles limit it, and how to keep it safe.

Each call to the Troopy API sends an API key in a header. The key says who calls, in which workspace, and what the call may do:

bash
curl -sS "$API/me" -H "Authorization: Bearer $TROOPY_API_KEY"

The API, the MCP server and the troopy CLI take the same keys.

Keys

A key is tr_live_ and 40 random characters. You make it in the app only: no operation of the API makes, renames or revokes a key. Thus a key can never make more keys.

  1. Open Settings > API keys.
  2. Type a Key name, and pick its Scopes.
  3. Select Create key, then Copy key.
  • Troopy shows the key one time. It keeps only a hash, so it cannot show the key again. A lost key needs a new key.
  • A workspace has at most 10 active keys. Revoke one to make another.
  • The list shows the start and the last 4 characters of each key, who made it, and when it was last used.
  • The person who made a key can revoke it. The owners and admins of the organization can revoke any key.
  • A revoked key stops at once, and Troopy keeps its record.

Viewers, approvers and guests make no keys.

Send the key

Send the key in one of these headers:

http
Authorization: Bearer tr_live_...X-API-Key: tr_live_...

Troopy reads the key from the headers only. A key in the query of a URL is never read, so the call fails with 401. The reason is that URLs stay in logs and in the history of a browser.

One key, one workspace

A key works in the workspace that you made it in. No request names a workspace: Troopy always gets it from the key. To work in another workspace, make a key in that workspace.

GET /me tells you the workspace and the scopes of a key. It needs no scope, so each key can call it.

A key acts as you

A key acts as the person who made it. A teammate's history records what the key wrote as your API key, with its name.

Your role decides what the key can do, at the time of each call:

  • When someone takes you out of the workspace, your keys stop at the next call.
  • An operation for owners and admins refuses your key when you are not an owner or admin.
  • When your role changes, your keys get the new role at once.

Scopes

A scope lets a key call a part of the API. You pick the scopes when you make the key. A new key gets only workspace:read unless you pick more. Each page of an operation names the scopes that it needs. The API reference lists them all.

  • A scope ends in :read or :write. A :write scope does not include its :read scope, so pick both.
  • To give a task to a teammate, the key also needs the scopes of the tools that the teammate uses.
  • To approve a call of a teammate, the key needs the scopes that the call needs.

Give each key only the scopes that its work needs. A script that reads tasks needs tasks:read only.

Errors

A key that is missing, wrong, revoked or expired gets 401 unauthorized. The WWW-Authenticate header points to the metadata that tells an agent how to sign in:

json
{  "type": "https://troopy.ai/docs/api/errors#unauthorized",  "title": "Unauthorized",  "status": 401,  "detail": "The API key is invalid, revoked or expired",  "hint": "Send an API key as `Authorization: Bearer tr_live_...`. Create one in Troopy under Settings.",  "requestId": "5f0c2b9e-8d1a-4c7e-9b3f-2a6d4e8c1f07"}

A key without a scope that the operation needs, or a person without the role, gets 403 forbidden. Its detail names the scope or the role. The errors table lists each error with its hint.

Apps and AI assistants

An MCP client, such as Claude or Cursor, can sign in with OAuth in place of a key. You approve the app and its scopes in the browser, and Settings > Security lists it. See Connect an AI assistant with MCP.

Keep keys safe

  • Make one key for each script, service or computer. Then you can revoke one and keep the others.
  • Give the key a name that tells you where it runs, such as Nightly CRM sync.
  • Keep the key in the secret store of your CI or your server, never in code.
  • On your own computer, use troopy login or read -rs TROOPY_API_KEY. The history of your shell keeps a key that you type in a command.
  • Revoke a key when its work ends, or when someone sees it.

Related