Check a Client token

POST

/v1/namespaces/{namespace}/tokens/verify

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

Verifies a token against this Namespace’s Signing keys and returns its claims. Use it to debug a token a relay refuses. A token signed by any other Namespace’s key gets a 401.

Authorizations

• apiKey
• session
• agentToken

Parameters

Path Parameters

namespace

required

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.

string

>= 3 characters <= 32 characters /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/

Example

acme

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

The request is malformed or a field is invalid. The message says which.

Media typeapplication/json

object

error

required

string

Example

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

401

The token is malformed, expired, has a bad signature, or wasn’t signed by one of this Namespace’s keys. Also returned when the caller isn’t authenticated.

Media typeapplication/json

object

error

required

string

Example

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

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"
}

404

No such thing, or not yours. Another customer’s Organization or Namespace is a 404 too, so nobody can tell which ones exist.

Media typeapplication/json

object

error

required

string

Example

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