Mint a Client token
const url = 'https://app.caprid.com/v1/namespaces/acme/tokens';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"path":"room/42","subscribe":""}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://app.caprid.com/v1/namespaces/acme/tokens \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "path": "room/42", "subscribe": "" }'Signs a Client token with one of the Namespace’s Signing keys. Use it when you’d rather not hold a Signing key’s secret in your own backend.
A token gets no grants by default. Name what it may publish, subscribe to, or both. A request that names neither is a 400. Whatever you ask for has to fit inside the Signing key’s scope.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”A Namespace’s name, which is the root of every path signed for it.
It never changes. Use lowercase letters, digits and hyphens, and start
and end with a letter or digit. Some names, like admin and
default, are reserved, and so is every name that starts with
trial-, which only Trial Organizations get.
Example
acmeRequest Body
Section titled “Request Body”object
The kid of the Signing key to sign with. You can leave it out when the Namespace has exactly one.
Where the token is rooted, relative to the Namespace. The
token’s root claim is <namespace>/<path>.
Seconds until the token expires. 0 means never.
Examples
Watch one room for an hour
{ "path": "room/42", "subscribe": ""}Publish your own broadcast and watch everyone else's
{ "path": "room/42", "publish": "alice", "subscribe": "", "expires_in": 14400}Responses
Section titled “Responses”The signed token and what it grants.
object
A JWT. Give it to the Client, which passes it to the relay as ?jwt=.
A Client token’s payload. root is absolute and starts with your
Namespace. put (publish) and get (subscribe) are prefixes relative
to root.
object
When the token expires. Absent for a token that never expires.
When the token was issued.
Example
{ "claims": { "root": "acme/room/42", "get": [ "" ] }}The request can’t be signed: it grants nothing, it asks for more than the key’s scope, it reaches outside the Namespace, or it names no key while the Namespace has zero or several.
object
Example
{ "error": "the requested grants exceed the key's scope"}No valid credential. Missing, expired and revoked credentials all get the same response, and so does an API key whose trial has lapsed. An Agent token from before a claim gets a 401 too, once the claim has made the trial a person’s, with a message saying to get a new token.
object
Example
{ "error": "the requested grants exceed the key's scope"}Headers
Section titled “Headers”Example
Bearer realm="switchboard"Sent with an API key limited to some Namespaces, to a Namespace outside its limit, or to a route that acts on the Organization as a whole. A limited key can never create API keys.
object
Example
{ "error": "this API key is limited to the Namespaces acme-staging, and acme isn't one of them"}The Namespace isn’t one you can reach, or the kid isn’t one of its keys.
object
Example
{ "error": "the requested grants exceed the key's scope"}