Exchange a Relay enrollment token for a Node key

POST

/cluster/enroll

curl --request POST \
  --url https://switchboard.mux.global/cluster/enroll \
  --header 'Content-Type: application/json' \
  --data '{ "token": "sbe_Vq3m..." }'

Spends a Relay enrollment token from POST /v1/organizations/{id}/enrollments and returns the Node, its Node key, and the values to put in the relay’s relay.toml. Run it once per relay, by hand or from your provisioning script.

The token is the only credential, and it works once. A second exchange is a 401. Keep the Node key. A relay that loses it has to be enrolled again as a new Node.

Request Body^required

Media typeapplication/json

object

token

required

string

Example

sbe_Vq3m...

Responses

201

Enrolled.

Media typeapplication/json

object

node

required

object

url

required

string

canonical

required

string

source

required

string

Allowed values: poll static

account

required

The oldest Namespace of the Organization that owns the Node. It names the owner. The relay still carries all of the Organization’s Namespaces.

string

region

required

string

gateway

required

boolean

client_url

The address Clients, such as a player page, use to reach this relay, when it differs from url, the address its peers dial. On a private network, url can be a name no Client can resolve, so whatever hands relay addresses to your Clients should read this field instead. It’s fixed at enrollment and omitted when the Node has none. /cluster/connect never returns it, because that list is only for peers to dial.

string

enrolled

required

boolean

first_seen_at

required

integer

last_seen_at

required

integer

live

required

boolean

node_key

required

The Node key. It goes in three places: the jwt= of both URLs below (already filled in), and the file that [cluster] token points to.

string

cluster

required

The relay’s [cluster] settings.

object

node

required

string

connect_api

required

string

auth

required

The relay’s [auth] settings.

object

url

required

string

Example

{
  "node": {
    "source": "poll"
  },
  "node_key": "sbn_9KfQ...",
  "cluster": {
    "node": "https://relay1.acme.example:4443/",
    "connect_api": "https://switchboard.mux.global/cluster/connect?jwt=sbn_9KfQ..."
  },
  "auth": {
    "url": "https://switchboard.mux.global/auth?jwt=sbn_9KfQ..."
  }
}

400

The request is malformed. The message says how.

Media typeapplication/json

object

error

required

string

Example ^generated

{
  "error": "example"
}

401

The token is unknown, expired, or already used.

Media typeapplication/json

object

error

required

string

Example ^generated

{
  "error": "example"
}

409

Another Node took this token’s URL after the token was issued. The token still works once that Node is deleted.

Media typeapplication/json

object

error

required

string

Example ^generated

{
  "error": "example"
}