Create a Relay enrollment token

POST

/v1/organizations/{id}/enrollments

curl --request POST \
  --url https://app.caprid.com/v1/organizations/4/enrollments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "https://relay1.internal.acme.example:4443/", "region": "iad", "gateway": true, "client_url": "https://live.acme.example/" }'

Issues a one-time token that a relay you run exchanges for its Node key, with POST /cluster/enroll. You decide everything about the Node here: its URL, its Region, whether it can be a Gateway, and its Client URL. The relay can’t change any of it later.

The token is shown once. It expires after expires_in seconds, or when it’s used, whichever comes first.

Authorizations

• apiKey
• session
• agentToken

Parameters

Path Parameters

id

required

integer

The Organization’s id, from GET /v1/organizations.

Example

4

Request Body^required

Media typeapplication/json

object

url

required

The URL peers will dial this relay on, and Clients too unless client_url names another. It needs a publicly trusted certificate for its host.

string format: uri

region

Which of your Regions the Node joins. Relays in the same Region all peer with each other. Region names belong to you, so your iad is unrelated to anyone else’s. Can’t contain /.

string

default: default <= 64 characters

gateway

Whether this Node may be elected its Region’s Gateway, which carries the Region’s traffic to other Regions.

boolean

client_url

The Client URL, which is where Clients, such as a player page, reach this relay when that isn’t url. Use it when url is a name only your private network resolves, and Clients come in through a public hostname or a load balancer. Switchboard doesn’t route anything with it. It reports the value on the Node, for whatever hands relay addresses to your Clients.

It has to start with http:// or https:// and can’t contain a username or password. Switchboard trims it and stores it as you send it. Leave it out, or send "", for none. The relay can’t change it. If the relay’s connect_api URL carries client=, that value has to match.

string format: uri

expires_in

Seconds until the token expires. 0 means the default. It always expires.

integer

default: 3600 <= 86400

Example

{
  "url": "https://relay1.internal.acme.example:4443/",
  "region": "iad",
  "gateway": true,
  "client_url": "https://live.acme.example/"
}

Responses

201

The pending enrollment, with its token.

Media typeapplication/json

object

id

required

Identifies the enrollment for revoking it. Not the token.

string

account

required

The Organization’s oldest Namespace, kept from before Organizations. The Node belongs to the whole Organization and carries all of its Namespaces. null when the Organization has no Namespaces.

string | null

url

required

The URL as you sent it.

string

canonical

required

The URL in the normalized form Switchboard uses to tell Nodes apart.

string

region

required

string

gateway

required

boolean

client_url

The Client URL the Node will have. Omitted when it has none.

string

preview

required

The first 6 characters of the token after sbe_.

string

created_at

required

integer

expires_at

required

integer

token

required

The Relay enrollment token. Shown only in this response.

string

Example

{
  "token": "sbe_Vq3mK8nR5tWb2xYc7dLp0sHf4jGu9eAz1oQi6vTk3wM"
}

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

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

409

A Node already exists at this URL. Delete it first.

Media typeapplication/json

object

error

required

string

Example

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