Skip to content
Caprid

Create an Organization

View .mdOpenAPI specOpen in ClaudeOpen in ChatGPT
POST
/v1/organizations
curl --request POST \
  --url https://app.caprid.com/v1/organizations \
  --header 'Content-Type: application/json' \
  --cookie __Host-switchboard_session=<__Host-switchboard_session> \
  --data '{ "namespace": "acme-labs", "name": "Acme Labs" }'

Creates another Organization, the way signup created your first. Use one to keep a separate customer, or a project you’ll hand over, apart from the rest. It has its own Namespaces, API keys, Members and relays.

You become its Owner. It is named after its Namespace unless you give it a name, which you can change later. The response holds its first API key, and this is the only time that key’s secret is shown, so store it now.

This takes a signed-in session. An API key acts for its own Organization, so it can’t create another.

An Account may create 5 Organizations. Organizations you joined by invitation don’t count. If you need more, ask Mux to raise your cap.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
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])?$/
name

For display. Defaults to the Namespace.

string
<= 100 characters

Example 

{
  "namespace": "acme-labs",
  "name": "Acme Labs"
}

Responses

Section titled “Responses”

201

Section titled “201”

The new Organization, its Namespace, and its first API key.

Media typeapplication/json
object
organization
required

A customer of Switchboard. It owns its Namespaces, and the API keys, Nodes and enrollments that serve them. Its Members manage all of it.

object
id
required

Identifies the Organization in routes. It never changes.

integer
name
required

For display. Any Member can change it.

string
role

Your role in it. Absent for an API key, which has none.

string
Allowed values: owner member
created_at
required
integer
trial_expires_at

When a Trial Organization lapses, so its Agent knows how long it has to get a person to claim it. Absent for every other Organization.

integer
namespace
required
object
name
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])?$/
organization_id
required

The Organization that owns it, for good.

integer
platform_peering
required

Whether its tracks may travel between your Self-hosted relays and Platform relays, the relays Mux runs.

boolean
created_at
required
integer
api_key
required
object
id
required

Identifies the key for revoking it. Not a secret.

string
label
required
string
preview
required

The first 6 characters of the secret after sb_, so you can tell keys apart.

string
created_at
required
integer
expires_at

Absent for a key that never expires.

integer
last_used_at

Absent for a key that has never been used.

integer
namespaces

The Namespaces the key is limited to, by name. Absent for a key with no limit. A deleted Namespace drops out, so a key whose Namespaces have all been deleted has [] here and can do nothing.

Array<string>
secret
required

The API key itself. Shown only in this response.

string

Example 

{
  "organization": {
    "id": 12,
    "name": "Acme Labs",
    "role": "owner",
    "created_at": 1792900000
  },
  "namespace": {
    "name": "acme-labs",
    "organization_id": 12,
    "platform_peering": false,
    "created_at": 1792900000
  },
  "api_key": {
    "id": "3f9a1c07be42",
    "label": "initial",
    "preview": "R2x0Z9",
    "created_at": 1792900000,
    "secret": "sb_R2x0Z9kQ7mVt3xLp8wNc1bYh5sDf2gJr6uEa0zWiTq4"
  }
}

400

Section titled “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

Section titled “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

Section titled “Headers”
WWW-Authenticate
string
Example 
Bearer realm="switchboard"

403

Section titled “403”

Sent with an API key, or you have already created as many Organizations as you may. The message says which.

Media typeapplication/json
object
error
required
string

Example 

{
  "error": "an Account may create 5 Organizations, and you have already; ask whoever runs this Switchboard to raise your cap"
}

409

Section titled “409”

The Namespace is taken. Namespace names are never reused, even after one is deleted.

Media typeapplication/json
object
error
required
string

Example 

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