The Company Agents API uses bearer tokens. Every request includes: 
Authorization: Bearer ca_prod_<token>
No cookies, no sessions, no OAuth dance for API use. The dashboard uses its own login session and is a separate concern.

​
Creating a token

From the dashboard: Settings → API Tokens → New token. Provide:
  • Name — a human-readable label (e.g., “ci-pipeline”)
  • Scopes — which resources this token can touch
  • Expiration — optional; tokens can live forever or expire on a date
From the CLI: 
company-agents token create \
  --name "ci-pipeline" \
  --scopes "read,write" \
  --expires 2027-04-11
The token value is shown once on creation. If you lose it, rotate it; you cannot recover the original. Token format: 
ca_prod_7f4b8a2c3d1e9f8a7b6c5d4e3f2a1b0c
  • ca_ — the product prefix
  • prod_ or dev_ — the instance environment
  • The remaining 32 hex characters — the token body

​
Scopes

Every token has a list of scopes. A request is allowed only if the token holds at least one scope matching the endpoint.
ScopeGrants
readAny GET on any resource
writeAny POST, PATCH, DELETE on any resource
adminRotating secrets, creating tokens, managing webhooks
company:<id>Restricts the token to one company
company:<id>:readRead-only access to one company
company:<id>:writeRead and write access to one company
The two broad scopes (read, write) are convenient. In production, prefer per-company scopes so a leaked token from one company cannot read another. Examples:
  • CI pipeline that creates tasks in one company: company:ampha-group:write
  • Metrics exporter that reads everything: read
  • Admin script for token rotation: admin

​
Checking a token

The simplest health check: 
curl -s http://localhost:3100/v1/whoami \
  -H "Authorization: Bearer $CA_API_TOKEN" | jq
Response: 
{
  "data": {
    "tokenId": "tok_a1b2c3",
    "name": "ci-pipeline",
    "scopes": ["company:ampha-group:write"],
    "createdAt": "2026-03-22T09:14:00Z",
    "expiresAt": "2027-04-11T00:00:00Z",
    "lastUsedAt": "2026-04-11T10:41:22Z"
  }
}
If the token is invalid or expired, the response is: 
{
  "error": {
    "code": "unauthorized",
    "message": "The provided token is not valid"
  }
}

​
Rotating a token

Rotating a token creates a new token with the same name and scopes, returns the new value, and marks the old one for deletion. The old one is still valid for a grace period (default 24 hours) so you can roll your deployments without downtime. 
company-agents token rotate tok_a1b2c3
The output prints the new token value and the grace period end time.

​
Revoking a token

Revocation is immediate. No grace period. 
company-agents token revoke tok_a1b2c3
Use revocation when:
  • A token has leaked
  • An employee with a personal token has left
  • A CI job has been taken out of service and will not roll

​
Listing tokens

company-agents token list
Returns every token for the current instance, including metadata about last use and which host last used it. There is no way to see the token value; only the metadata.

​
Token best practices

  • One token per caller. Do not share a token between two pipelines. If one leaks, you have to rotate both.
  • Scope tightly. Prefer company:<id>:write over a global write.
  • Short-lived where possible. For CI tokens, expire after 90 days and rotate as part of the pipeline.
  • Store in a secret manager. Never commit a token to a repo, even a private one.
  • Audit the list quarterly. Delete tokens that have not been used in the last 30 days.

​
Authentication for adapters

Adapters do not use API tokens. Adapters authenticate as a specific agent using an agent token, which is a different credential scoped to a single agent’s actions. See the adapters overview and secrets for how agent tokens work.

​
Next

  • Companies — the first resource you will call
  • Agents — hire an agent through the API
  • Activity — how to see what calls a token has made recently