Check a Client token

Deprecated

POST

/v1/tokens/verify

curl --request POST \
  --url https://app.caprid.com/v1/tokens/verify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "token": "example" }'

POST /v1/namespaces/{namespace}/tokens/verify for the API key’s only Namespace.

Authorizations

• apiKey
• session
• agentToken

Request Body^required

Media typeapplication/json

object

token

required

string

Example ^generated

{
  "token": "example"
}

Responses

200

The token is valid.

Media typeapplication/json

object

kid

required

string

claims

required

A Client token’s payload. root is absolute and starts with your Namespace. put (publish) and get (subscribe) are prefixes relative to root.

object

root

string

put

Array<string>

get

Array<string>

exp

When the token expires. Absent for a token that never expires.

integer

iat

When the token was issued.

integer

expires_in

Seconds left. Absent for a token that never expires.

integer

Example

{
  "claims": {
    "root": "acme/room/42",
    "get": [
      ""
    ]
  }
}

400

Sent with a session, or with an API key that doesn’t reach exactly one Namespace. Use the route the message names instead. This route also returns 400 for anything that route would refuse with 400.

Media typeapplication/json

object

error

required

string

Example

{
  "error": "this API key reaches 2 Namespaces, so this route can't tell which one you mean; use /v1/namespaces/{namespace}/keys"
}

401

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.

Media typeapplication/json

object

error

required

string

Example

{
  "error": "the requested grants exceed the key's scope"
}

Headers

WWW-Authenticate

string

Example

Bearer realm="switchboard"

403

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.

Media typeapplication/json

object

error

required

string

Example

{
  "error": "this API key is limited to the Namespaces acme-staging, and acme isn't one of them"
}