Skip to main content
Agent tokens are the simplest way to authenticate an AI agent. They work exactly like API keys — a long-lived string sent in the Authorization: Bearer header — but scoped to one agent rather than the whole tenant.
For production agents, upgrade to Ed25519 sessions. Agent tokens are great for prototypes and simple deployments; Ed25519 gives you short-lived sessions, replay protection, and per-session revocation.

​
Token format

agent_test_Lp3xRk9WmNvQj2TbDfE4YhCsV7Z1...
│   │      └─ random suffix
│   └──────── environment prefix
└──────────── "agent_"

​
Obtain a token

When you create an agent, Sly returns a token as part of the response: 
curl -X POST https://sandbox.getsly.ai/v1/agents \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "parent_account_id": "acc_...",
    "name": "Payables Bot",
    "kya_tier": 1
  }'
Response includes: 
{
  "data": {
    "id": "agt_...",
    "name": "Payables Bot",
    "kya_tier": 1,
    ...
  },
  "credentials": {
    "token": "agent_test_Lp3xRk9WmNvQj2...",
    "warning": "SAVE THIS TOKEN NOW — it will never be shown again!"
  }
}
The token is shown once. Store it securely immediately.

​
Use the token

Exactly like an API key: 
curl https://sandbox.getsly.ai/v1/wallets \
  -H "Authorization: Bearer agent_test_Lp3xRk9WmNvQj2..."
The server populates a RequestContext identifying the actor as this agent — so:
  • Transfers default to this agent as the initiator
  • Balances show this agent’s wallet
  • Spending is enforced against this agent’s wallet policy and KYA tier limits

​
Rotate a token

curl -X POST https://api.getsly.ai/v1/agents/$AGENT_ID/rotate-token \
  -H "Authorization: Bearer $API_KEY"
Response returns a new agent_* token. The old token is invalidated immediately.

​
Revoke a token

Delete the agent or freeze it: 
# Freeze (token becomes non-functional, agent record preserved)
curl -X POST https://api.getsly.ai/v1/agents/$AGENT_ID/freeze \
  -H "Authorization: Bearer $API_KEY"

# Delete (permanent)
curl -X DELETE https://api.getsly.ai/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $API_KEY"

​
When agent tokens are enough

  • Prototyping and local dev — fastest path to a working agent
  • Trusted environments — agent runs on your own server, not user machines
  • Low-value scopes — read-only agents, monitoring agents, observability collectors
  • Backwards compatibility — existing agents don’t need to migrate

​
When to upgrade to Ed25519 sessions

  • Production — real money, real merchant traffic
  • Agent runs on customer hardware — keypair never leaves the machine
  • You need replay protection — sessions bound to nonces
  • You need granular revocation — kill one session without rotating the token
  • You want push events — sess_* tokens unlock the persistent SSE channel
See Ed25519 sessions for the upgrade path. Migration requires zero changes to route code — both methods produce identical RequestContext.

​
Comparison with API keys

Agent tokens and API keys both send a long-lived secret in the header. The differences:
Agent token (agent_*)API key (pk_*)
ActorOne specific agentWhole tenant
Scope enforcementPer-agent policy + KYA tierScope list + tenant
KYA tier appliesYesNo
Wallet policy appliesYesNo
Typical lifespanWeeks-months, rotated per agent lifecycleMonths-years, rotated per security policy