Keys and tokens
The credentials an app or an agent uses to work in Cypress, who each one acts as, where it is made, and how to show an agent only the tools its job needs.
TL;DRAI summary
Every interaction with Cypress uses a specific key or token to verify your identity and permissions. This chapter explains the different types of credentials, what they do, where they work, and how to manage them, ensuring your operations are secure and correctly authorized.
Every call to the API and every MCP tool carries one credential, as an
Authorization: Bearer … header. Which one you use decides who the call
acts as: the rules applied are always those of that member in the app.
The credentials
| Credential | Starts with | Acts as | Made in | Lasts |
|---|---|---|---|---|
| API key | cyp_live_ | Your organization, through its first active admin or fleet manager | Organization → Integrations, by an admin | Until revoked |
| Sandbox key | cyp_test_ | The sandbox organization, the same way | By Cypress, with the sandbox | Until the sandbox is reset |
| App token for a person | cyp_at_ | The person who approved the app, with their role | Connect Cypress, when an admin approves your app | An hour; renewed with a refresh token (cyp_rt_) |
| Agent token | cyp_at_ | One agent your app added, under its own name | Connect Cypress, step 5 | An hour; ask for a new one |
| CM token | cyp_cm_ | A Cypress Manager, for the organization each call names | Settings › Developers, by a Cypress Manager | 30, 90, 180 or 365 days |
Which one to use:
- Your own system (a fleet database, a DMS, an ERP) working for your organization: an API key.
- An AI agent you run yourself, connected to the MCP servers: an API key, scoped to what the agent's job needs. To try it first, a sandbox key.
- An app many organizations use, or an agent platform that adds its own agents: Connect Cypress. Each organization's admin approves it once.
- Cypress staff working for a customer or on the staff screens: a CM token.
Where each one works
The app's actions, the MCP servers and most of the API take every credential above. A few routes take an API key only, because they belong to the system that runs your integration rather than to a person or an agent:
- managing webhook subscriptions and reading the delivery log
(
/api/v1/webhooks/subscriptions,/api/v1/deliveries); - disconnecting an app (
DELETE /api/v1/connections/{id}); - pushing and keeping your vehicle data current: creating, replacing and deleting vehicles, their costs, odometer readings, purchase and financing, departures and sold-elsewhere reports, and the bulk routes.
A route that takes keys only answers a token with 401, "This endpoint
accepts API keys only; app and agent tokens are not accepted here". The
Cypress staff actions take a CM token only, with two exceptions since
1.9.0: a first-party app acting for Cypress staff for one organization (Grove
for a Cypress Manager) may roll back a closing (rollback_closing) and
confirm a step or a payment (run_closing_staff_action with confirm or
confirm_payment), holding closing:write, on a closing that organization
sells or buys in. Any other organization's closing answers 404; every other
staff action answers 403 POLICY_DENIED.
A live key and a test key
A key's prefix says where it acts. A test key on a live organization, or a
live key on a sandbox, answers 403 KEY_ENVIRONMENT and does nothing.
Never test with a live key: build against a sandbox, and use the live key
only in the system that runs your integration. The format, the checksum and
what a secret scanner can match are in
Live and test keys.
Scopes: what a credential may do
A key or a token holds scopes, one or two per area: tasks:read,
tasks:write, crm:write, offers:write, planning:read and so on. A call
outside them answers 403 SCOPE_MISSING, and an MCP client is never shown a
tool the credential can't use. Give an agent the scopes its job needs, and no
more. The full list is in Key scopes.
To see what a credential may do, and why not, call GET /api/v1/organization
(the MCP tool get_organization). It answers the organization, the key's
scopes, the products switched on, every capability with the reason it is
refused, if it is, and the organization's Cypress Manager.
Toolsets: what an agent is shown
An agent picks the right tool more reliably when it sees fewer of them, so
Cypress Operate shows it the core tools by
default: thirteen tools for the everyday work, and every other operation
through discover. Add ?toolsets= to the server's address to show an area's
own tools beside them, or all for every operation as a tool of its own:
https://app.getcypress.ai/api/mcp/operate?toolsets=core,remarketingToolsets never widen what a credential may do. The scopes decide what it may do, and the toolsets what it is shown. A suggested set for each role is in Tools by area.
Revoking
- An API key: revoke it in Organization → Integrations. It stops at once.
- An app and its agents: an admin disconnects the app in Settings ›
Connected apps. Every token ends at once and its agents are switched off.
An integration can do it too, with
connections:write. - A CM token: revoke it in Settings › Developers.
- A sandbox key: ask for a reset. The old key stops and a new one is issued.
If a key or a token is ever pasted where it should not be, revoke it and make another. Everything a credential did stays in the activity log, under the name of whoever it acted as.
What an agent can and cannot do
An AI agent works in your organization under the app's rules. What it may do in each area, the decisions that always stay with a person, and how a refusal comes back.
MCP servers
Connect an AI agent to Cypress over the Model Context Protocol, to work in your organization or to read what Cypress knows.