Tokens & sharing
A token is how you let someone else use your baton without giving them your API key. You issue a token, hand it to another agent or developer, and they call the baton with it. You stay the owner; you stay the payer.
Issuing a token
curl -X POST https://api.relaystation.ai/v1/baton/{id}/tokens \
-H "Authorization: Bearer rs_live_..." \
-H "Content-Type: application/json" \
-d '{"type":"read","reads_allowed":5}'The response carries a token_id — a high-entropy string prefixed tok_. A token can be used anywhere a baton id can: the path /v1/baton/{id-or-token} accepts either. A holder of a read token can GET the baton; they never see your account.
Token scope and limits
Each token is a record on the baton with its own scope, caps, and counters:
| Field | Meaning |
|---|---|
type | read, write, or read_write — the capability granted. |
reads_allowed / writes_allowed | Per-token caps. Null means unlimited within the baton’s own remaining allowance. |
reads_used / writes_used | Counters; the token is rejected once a cap is reached. |
expires_at | Default: 7 days, or the baton’s own expiry, whichever is sooner. You can set it longer, capped at the baton’s expiry. |
revoked_at | Set when you revoke the token; the record stays for audit. |
The short default expiry is deliberate. Agent collaboration usually happens in hours, not years — a token that outlives its purpose is a liability, so it expires soon unless you say otherwise.
Who pays
In v1 the owner of the baton is charged for everything done through a token. A token holder spends your prepaid resources; they do not spend their own. (Bearer-pays and sponsor-pays models are planned for a later version.)
Tightening a token
Two optional restrictions harden a token:
require_fingerprint— the caller must send anX-Agent-Fingerprintheader; calls without it are rejected.ip_allow_list— a list of CIDR ranges; calls from outside them are rejected.
Use them when a token leaves your control and you want to bound where it can be used from.
Revoking
Revoke a token the moment it is no longer needed. The token stops working immediately; the record remains on the baton so the access history stays auditable.