Token exchange reference

Exchange a key

Exchanges a key for an access token of one audience that acts as the key's member, you or an Agent, with the member's current role and the key's narrowing, in the key's account only. Use it for a key that acts as an Agent, which Streams and the Management API never take directly, or when the credential your program holds should expire on its own. A key that acts as you is also accepted directly. Revoking the key stops its exchanges at once; Streams refuses its tokens shortly after, and every token expires within 600 seconds anyway.

Request

Answer

200, application/json, Cache-Control: no-store. An exchange's token and what it acts as. It may carry other members kept for older clients, such as api_key_id; ignore them.

A refusal answers as Refusals lists.

Example

curl -sS -X POST "https://tonbo.dev/api/iam/token" \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audience":"https://streams.tonbo.dev"}'

Down-scope a token

Mints, from a key or a Streams token, a Streams token that reaches only the streams and databases it names, read-only unless it asks otherwise, for one client such as a web page. The new token acts as its subject's member, in the subject's account, and is never wider than its subject: a request for anything the subject does not reach is refused, never trimmed. A down-scoped token may be down-scoped again, each step only narrowing. No name needs to exist yet; Streams answers 404 for a missing one within reach. Revoking the key the chain came from stops every token in it. A request is checked in this order: its fields, then the subject, then the names, then the lifetime.

Request

Answer

200, application/json, Cache-Control: no-store. The narrower Streams token and what it reaches.

A refusal answers as Refusals lists.

Example

PAGE_TOKEN=$(jq -n --arg key "$TONBO_API_KEY" '{
    grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
    subject_token: $key,
    subject_token_type: "urn:tonbo:params:oauth:token-type:api_key",
    streams: ["events"],
    read_only: true,
    expires_in: 300
  }' | curl -sS -X POST "https://tonbo.dev/api/iam/token" \
  -H "Content-Type: application/json" -d @- | jq -r .access_token)

Audience

The API a token is for, by its name, which is not the origin a request goes to. https://streams.tonbo.dev is Tonbo Streams: its token works at the Streams origin and the database origin of every region. https://api.tonbo.dev is the Management API at https://api.tonbo.dev/v1.

• https://streams.tonbo.dev
• https://api.tonbo.dev

StreamName

A stream by the name tonbo stream list shows, without s.: 1 to 83 lowercase letters, digits, dots, underscores and hyphens, starting and ending with a letter or digit, without .., not starting with m., vol., s., session. or proc., and not streams or new.

A string. 1 to 83 characters. Matches ^(?!m\.)(?!vol\.)(?!s\.)(?!session\.)(?!proc\.)(?!(?:streams|new)$)(?!.*\.\.)[a-z0-9](?:[a-z0-9._-]{0,81}[a-z0-9])?$.

StreamPrefix

The start of stream names: 1 to 83 lowercase letters, digits, dots, underscores and hyphens, starting with a letter or digit, not starting with m., vol., s., session. or proc.. It reaches every stream whose name starts with it.

A string. 1 to 83 characters. Matches ^(?!m\.)(?!vol\.)(?!s\.)(?!session\.)(?!proc\.)[a-z0-9][a-z0-9._-]{0,84}$.

DatabaseName

A database by the name tonbo database list shows: 1 to 85 lowercase letters, digits, dots, underscores and hyphens, starting and ending with a letter or digit, without .., not starting with m., vol., s., session. or proc., and not streams or new.

A string. 1 to 85 characters. Matches ^(?!m\.)(?!vol\.)(?!s\.)(?!session\.)(?!proc\.)(?!(?:streams|new)$)(?!.*\.\.)[a-z0-9](?:[a-z0-9._-]{0,83}[a-z0-9])?$.

DatabasePrefix

The start of database names: 1 to 85 lowercase letters, digits, dots, underscores and hyphens, starting with a letter or digit, not starting with m., vol., s., session. or proc.. It reaches every database whose name starts with it.

A string. 1 to 85 characters. Matches ^(?!m\.)(?!vol\.)(?!s\.)(?!session\.)(?!proc\.)[a-z0-9][a-z0-9._-]{0,84}$.