Agent tokens

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.

Cross-agent operations require explicit elevation

By default, an agent_* token is single-agent-scoped — the agent can only act on its own resources. Reading sibling agents, mutating their state, or moving funds between them returns 403 SCOPE_REQUIRED with a hint to call request_scope. Tenant owners approve the request via the dashboard or the API. See Scope grants for the full lifecycle, the three tiers (tenant_read, tenant_write, treasury), and the canonical list of currently-gated routes.

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_*`)
Actor	One specific agent	Whole tenant
Scope enforcement	Per-agent policy + KYA tier	Scope list + tenant
KYA tier applies	Yes	No
Wallet policy applies	Yes	No
Typical lifespan	Weeks-months, rotated per agent lifecycle	Months-years, rotated per security policy

Get Started

Onboarding

Migration

Authentication

Core Concepts

Guides

Recipes

Architecture

Settlement & Treasury

Stellar

Protocols

Agent Platform

SDKs & Tools

Webhooks

Resources

Agent tokens

Token format

Obtain a token

Use the token

Rotate a token

Revoke a token

When agent tokens are enough

When to upgrade to Ed25519 sessions

Cross-agent operations require explicit elevation

Comparison with API keys

​Token format

​Obtain a token

​Use the token

​Rotate a token

​Revoke a token

​When agent tokens are enough

​When to upgrade to Ed25519 sessions

​Cross-agent operations require explicit elevation

​Comparison with API keys

Token format

Obtain a token

Use the token

Rotate a token

Revoke a token

When agent tokens are enough

When to upgrade to Ed25519 sessions

Cross-agent operations require explicit elevation

Comparison with API keys