Two kinds of credential

The mode is in the prefix, so it is visible wherever the token is — in a log, a config file, a code review — rather than being a setting somebody has to remember to check.

• xyr_live_…
  Reads and writes this workspace’s records.
• xyr_test_…
  Reads this workspace’s real records and never writes. A write is checked exactly as a live one would be and answered with simulated: true, and nothing is recorded. The order and identity routes, which can only write for real, refuse it.

A test credential is judged by exactly the same checks a live one is. A rehearsal that skipped the decision, or that sent a real request to a customer’s server, would not be a rehearsal.

A token carries only the scopes it was given. An endpoint that needs one it does not have is refused with forbidden, and the message names the scope rather than leaving you to guess which of them was missing.

• read:analytics
  Read campaign and revenue reporting
• read:contacts
  Read contacts and segments
• write:contacts
  Create and update contacts
• write:orders
  Report orders for revenue attribution
• write:postsreaches people
  Create and schedule social posts
• send:campaignsreaches people
  Send email and SMS campaigns
• read:growth
  Read missions, decisions, signals, opportunities, experiments, outcomes, approvals and proposed changes
• write:experiments
  Write down hypotheses against tests before they are decided
• write:actions
  Propose changes for a person to approve; nothing is carried out without one
• write:eventsreaches people
  Report what contacts did in your own systems, which can start workflows that message them
• read:events
  Read the events a webhook can subscribe to
• manage:members
  Provision, change and remove members from an identity provider, over SCIM
• read:agents
  Read this workspace’s agents, the tools they may use, and the rules that govern them

The marked scopes let a token reach people outside the workspace — sending, posting, or reporting events that can start a workflow which messages somebody. Grant them only to an integration that genuinely sends, and never to one that only reads.

Issued in Agent controls, with the owner. It is deliberately not something a token can mint: registering an agent widens what may act in the workspace, and a leaked key that could do that would be worse than any convenience it bought.

• Carries
  No scopes. What the agent may do is decided per request by the gateway, against the workspace’s permissions, the data, the risk and the owner’s rules.
• Stands for
  One agent. Revoking it stops that agent and nothing else — unlike a workspace token, which is the workspace.
• Limit
  1200 requests an hour, per credential.

Authorization: Bearer xyr_agt_…

What comes back, and how to read it, is on the Agent API page.

A token is replaced with an overlap, so the new one works before the old one stops and nothing has to be swapped in a single instant. The overlap is chosen from a fixed set of 0h, 1h, 24h, 168h — 24h by default — rather than being free text, because "forever" is not an overlap.

• Overlap
  Both tokens work. Deploy the new one, confirm it, then let the old one lapse.
• After the overlap
  The replaced token stops — or sooner, if it was already due to expire.
• Revoked
  Stops at once, with no overlap. This is what a leak calls for.