# 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

```bash
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 an `X-Agent-Fingerprint` header; 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.