Skip to content
BageBage Docs

Get or refresh the agent token

POST
/v1/token
curl --request POST \
  --url https://api.trybage.com/v1/token \
  --header 'Content-Type: application/json' \
  --data '{ "client_assertion": "eyJhbGciOiJFZERTQSIsInR5cCI6ImNsaWVudC1hc3NlcnRpb24rand0In0...", "grant_type": "urn:openid:params:grant-type:ciba", "auth_req_id": "req_3f9c2b1a", "refresh_token": "rt_Xk2…" }'

With grant_type urn:openid:params:grant-type:ciba: call every interval seconds after bc-authorize (or once, after Bage calls back in ping mode). While the person decides, the answer is 400 authorization_pending. Each approved request gives one agent token (15 minutes), a refresh token and the person’s account link.

With grant_type refresh_token: a new agent token and a new refresh token for the same sign-in, without asking the person. Refresh tokens work once each; using one twice ends the sign-in. An “Allow once” sign-in can be refreshed for 8 hours after the person approved, an “Always” one until it goes 30 days unused. The person revoking the agent, or the website cutting it off, ends it too.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
client_assertion
required

A one-time JWT signed with the agent’s private key (RFC 7523). See the description at the top.

string
grant_type
required
string
Allowed values: urn:openid:params:grant-type:ciba refresh_token
auth_req_id

With the CIBA grant type.

string
refresh_token

With the refresh_token grant type.

string

Responses

Section titled “Responses”

200

Section titled “200”

The person approved.

Media typeapplication/json
object
token_type
required
string
Allowed value: agent
agent_token
required

A JWT (typ: agent+jwt, EdDSA). Send it to the website in the agent-token header, and sign each request with Web Bot Auth.

string
expires_in
required
integer
scope
required
string
refresh_token

Exchange it at /v1/token for the next agent token. Single use. Absent once the sign-in can’t be extended.

string
refresh_expires_in

Seconds until the refresh token stops working.

integer
account_link

Only on sign-in. This agent’s stable handle for the person; use it as login_hint next time instead of their email.

string

Example 

{
  "token_type": "agent",
  "expires_in": 900,
  "scope": "browse cart",
  "refresh_expires_in": 28800,
  "account_link": "lnk_9QbV2xS7kq4mWd1e"
}

400

Section titled “400”

authorization_pending (keep polling), access_denied (the person said no), expired_token (nobody answered in 5 minutes), invalid_grant (unknown or already used request, or a refresh token that is unknown, used, expired or ended), unsupported_grant_type.

Media typeapplication/json
object
error
required
string
error_description
string

Example 

{
  "error": "authorization_pending"
}

401

Section titled “401”

invalid_client

Media typeapplication/json
object
error
required
string
error_description
string

Example 

{
  "error": "authorization_pending"
}