Agent logins
Start a login, check it and end it. The login token pays for assets with the person's credits.
Start a login
POST /api/v1/agent-logins/
Content-Type: application/json{ "client": "claude-code", "name": "Claude Code" }| Field | Details |
|---|---|
client | claude-code, codex, cursor, gemini-cli, other or unknown. Default unknown. |
name | A label shown on Connected agents, up to 80 characters. |
scopes | A JSON list of scope names, or omit it for the defaults: assets:read, assets:write, games:write. |
No authentication. HTTP 201:
{
"login_id": "2d9e...",
"token": "rbk_...",
"approval_url": "https://rosebud.ai/connect/assets#<secret>",
"status": "pending",
"expires_at": "2026-10-27T18:34:11Z",
"scopes": ["assets:read", "assets:write", "games:write"]
}Keep token secret and give only approval_url to the person. The token works once they approve, within 30 minutes. They approve the whole set of scopes shown.
Scopes
scopes defaults to all three below, also when it's null. Otherwise it must be a list of one to ten of these names; anything else, including games:read and [], returns 400 invalid_scope.
| Scope | Lets the token |
|---|---|
assets:read | List and read the person's assets and jobs. |
assets:write | Quote and start paid jobs, cancel them, and rename or restore assets. |
games:write | Import a new game into the account, and open an upload session for one. |
No scope deletes assets, uploads to My assets, manages keys or reads usage. A login token isn't an agent token: importing a game with it creates that game's own connection (agent_token), which keeps working after the login is revoked or expires, until its own 90 days run out.
Check the login
GET /api/v1/agent-logins/current/
Authorization: Bearer rbk_...{
"login_id": "2d9e...",
"status": "active",
"client": "claude-code",
"name": "Claude Code",
"scopes": ["assets:read", "assets:write", "games:write"],
"expires_at": "2027-01-25T18:04:11Z",
"account": { "display_name": "Sam", "balance": 12400 }
}status is pending, active, expired or revoked. expires_at is the approval deadline while pending, then the token's expiry: 90 days after its last use. balance is a credit count or "unlimited"; account is null when the token doesn't work. A check counts as use.
Each use moves the expiry 90 days ahead, written at most once a day, so it can trail the last use by up to a day. An expired token is never renewed: the person approves a new login.
End the login
DELETE /api/v1/agent-logins/current/
Authorization: Bearer rbk_...HTTP 204. Cancels a pending login or revokes an approved one, even an expired one. Revoking takes effect on the next request.
Errors on the publishing endpoints
Publishing endpoints answer login errors as { "error": { "code", "message", "required_scope"? } }, and a 401 carries WWW-Authenticate: Bearer realm="api". The asset endpoints answer the same codes as { "detail", "code" }.
| Code | Status | When |
|---|---|---|
login_pending | 403 | The login still waits for approval. |
login_inactive | 401 | The login was cancelled or revoked, or its approval link expired before approval. |
key_expired | 401 | The token went 90 days without use. The person approves a new login. |
insufficient_scope | 403 | The token lacks the scope in required_scope. Start a new login with the default scopes. |
invalid_key, invalid_token | 401 | The token is unknown, malformed or revoked. |
invalid_scope | 400 | A new login asked for a scope it can't have. |