Skip to main content
Every request to the Topo API must be authenticated with an API key. Keys are scoped to the exact permissions your integration needs, so you can grant read-only access to one key and full write access to another — all within the same workspace.

​
Create an API key

1

Open your workspace settings

Navigate to Settings → Developers → API Keys in the Topo dashboard.
2

Create a new key

Click Create Key, give it a descriptive name (e.g. crm-sync-production), and select the scopes your integration requires.
3

Copy and store the key securely

Your key is shown once immediately after creation. Copy it to a secure secret store (such as your CI/CD secrets manager or a vault). Topo does not store the raw key value — if you lose it, you must rotate to a new one.
API keys are only displayed once at creation time. Store your key in a secrets manager immediately — you cannot retrieve it again from the Topo dashboard.

​
Pass the key in requests

Include your API key as a Bearer token in the Authorization header of every request: 
curl https://api.topo.io/v1/me \
  -H "Authorization: Bearer topo_xxxxxxxxxxxx"
Requests without a valid Authorization header are rejected with a 401 Unauthorized response before they reach any endpoint logic.

​
Available scopes

Scopes follow a resource:action naming convention. Grant only the scopes your integration actually uses.
ScopeWhat it allows
contacts:readRead contacts in your workspace
contacts:writeCreate and update contacts
sequences:readRead sequences and enrollment status
sequences:writeEnroll or remove contacts from sequences
contact_lists:readRead contact list definitions and memberships
contact_lists:writeCreate and manage contact lists
account_lists:readRead account list definitions and memberships
account_lists:writeCreate and manage account lists
activities:readRead the outreach activity stream
webhooks:readRead webhook subscriptions
webhooks:writeCreate, update, and delete webhook subscriptions
exclusions:readRead contact and company exclusion rules
exclusions:writeCreate and delete exclusion rules
tasks:readRead tasks in your workspace
tasks:writeCreate and update tasks

​
Verify your key with GET /v1/me

The /v1/me endpoint returns the identity and permissions of the calling key — useful for confirming your key is valid and that it carries the scopes you expect. 
curl https://api.topo.io/v1/me \
  -H "Authorization: Bearer topo_xxxxxxxxxxxx"
Response
​
id
string (UUID)
required
Unique identifier of the API key.
​
organization_id
string (UUID)
required
The workspace this key belongs to.
​
name
string
required
The human-readable name you gave this key at creation time.
​
key_prefix
string
required
The leading characters of the raw key value — safe to display in logs or UIs to identify which key was used.
​
scopes
string[]
required
List of permission scopes granted to this key.
​
created_at
string (ISO 8601)
required
Timestamp of when the key was issued.
​
last_used_at
string (ISO 8601) | null
required
Timestamp of the last request made with this key, or null if it has never been used.
Example response 
{
  "id": "018f1a2b-3c4d-7e8f-9a0b-1c2d3e4f5a6b",
  "organization_id": "018e9d8c-7b6a-7f5e-4d3c-2b1a0f9e8d7c",
  "name": "crm-sync-production",
  "key_prefix": "topo_xxxx",
  "scopes": ["contacts:read", "contacts:write"],
  "created_at": "2024-11-01T09:00:00Z",
  "last_used_at": "2025-01-15T14:23:11Z"
}

​
Authentication error responses

HTTP statustypeWhen it occurs
401 UnauthorizedUnauthorizedIssueThe Authorization header is missing, malformed, or the key is invalid
403 ForbiddenUnauthorizedIssueThe key is valid but does not have the required scope for this endpoint
See Errors & Rate Limits for the full error response shape.

​
Security best practices

One key per integration. Create a separate API key for each integration or deployment environment (e.g. crm-sync-staging vs crm-sync-production). This limits the blast radius if a key is compromised and makes it easier to audit usage.
  • Least privilege — only request the scopes your integration needs. A read-only reporting tool should never have write scopes.
  • Rotate regularly — retire old keys and issue fresh ones periodically, or immediately after any suspected exposure.
  • Never commit keys to source control — use environment variables or a secrets manager to inject keys at runtime.
  • Monitor last_used_at — keys that haven’t been used recently may be safe to revoke.