Get a Signing key

GET

/v1/namespaces/{namespace}/keys/{kid}

curl --request GET \
  --url https://app.caprid.com/v1/namespaces/acme/keys/acme_backend \
  --header 'Authorization: Bearer <token>'

Returns the full JWK, secret included. A kid that isn’t one of this Namespace’s is a 404.

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

kid

required

string

Example

acme_backend

The key’s kid, which is <namespace>_<label>.

Responses

200

The key.

Media typeapplication/json

A Signing key in JSON Web Key form, with the scope extension moq relays understand. k is the secret. Anyone holding it can sign tokens within the scope.

object

alg

required

string

Allowed value: HS256

key_ops

required

Array<string>

kty

required

string

Allowed value: oct

k

required

The HMAC secret, base64url without padding.

string

kid

required

string

scope

required

What a Signing key may sign. put is publish and get is subscribe, as in the token claims. Both are relative to root.

object

root

string

put

Array<string>

get

Array<string>

Example

{
  "alg": "HS256",
  "key_ops": [
    "sign",
    "verify"
  ],
  "kty": "oct",
  "kid": "acme_backend",
  "scope": {
    "root": "acme"
  }
}

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

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