Organizations and Namespaces

Your company is an Organization on Switchboard. The people who manage it are its Members. Each Member signs in with their own Account, so nobody shares a login, and one person can be a Member of several Organizations.

An Organization owns its Namespaces. A Namespace is the first segment of every path you can sign Client tokens for. If your Namespace is acme, you can sign any path under acme/, which covers all your broadcasts and their tracks. The name is yours for good. Nobody else can ever have it, even after you stop using it.

Signing up creates an Organization with the Namespace you choose. An AI agent can also start a trial Organization by itself, which becomes yours when you claim the agent. See AI agents.

Find your Organization’s id

API routes name what they act on. Signing keys and Client tokens belong to a Namespace, so their routes start with /v1/namespaces/acme. API keys and Self-hosted relays serve the whole Organization, so their routes start with /v1/organizations/{id}. To find the id, list your Organizations:

curl https://app.caprid.com/v1/organizations \
  -H "Authorization: Bearer $SB_API_KEY"

The response is:

[{"id": 4, "name": "acme", "created_at": 1790298000}]

The examples in these docs use Organization 4, which owns the Namespace acme.

Paths in the API and in tokens

When you call the API, paths are relative to the Namespace, and Switchboard adds the Namespace for you. Ask for room/42 and you get acme/room/42.

Inside a Client token, the path is written out in full, Namespace included. So when you sign tokens yourself, you write acme/room/42.

Create another Organization

You might want a separate Organization for a customer or project that should have its own API keys and relays. Create one from New Organization in the dashboard. You pick its first Namespace the same way you did at signup, you become its Owner, and its page shows its first API key once.

You can create 5 Organizations. Organizations you joined by invitation don’t count. Creating one takes a signed-in session, so an API key can’t do it.

Create a Namespace

An Organization can have more than one Namespace. A second Namespace is useful for keeping prod and staging apart, as Prod and staging shows. Any Member can create one, from the Organization’s page in the dashboard or with the API:

curl https://app.caprid.com/v1/organizations/4/namespaces \
  -H "Authorization: Bearer $SB_API_KEY" \
  -d '{"namespace": "acme-staging"}'

The response is the new Namespace:

{"name": "acme-staging", "organization_id": 4, "platform_peering": false, "created_at": 1790298000}

Names follow the same rules as at signup. Because a name is never reused, you get a 409 for any name that a Namespace has ever had, including one that was deleted.

An Organization can have 10 Namespaces at a time. Ask us if you need more.

Delete a Namespace

Only an Owner signed in to the dashboard can delete a Namespace. Use the Namespace’s settings tab, or call DELETE /v1/namespaces/acme-staging with your session. An API key can never delete one, so a leaked key can’t destroy something you can’t get back.

Deleting a Namespace:

• deletes its signing keys, so the Client tokens they signed stop working, and relays drop its tracks within about a minute
• removes it from the limit of any API key that was limited to it
• leaves your Self-hosted relays, Regions and enrollments alone, because they belong to the Organization

You can’t undo the delete, and nobody can use the name again, you included. You can delete your last Namespace. The Organization stays, with no Namespaces, until you create another.

Members and Owners

Every Member can manage everything the Organization owns. Owners can also change who is an Owner, remove Members, and invite people.

To see who belongs, open your Organization’s Members page in the dashboard, or call the API:

curl https://app.caprid.com/v1/organizations/4/members \
  -H "Authorization: Bearer $SB_API_KEY"

The response lists each Member with their role and when they joined, in Unix seconds:

[
  {"account_id": 7, "email": "bob@acme.example", "role": "owner", "joined_at": 1790294400},
  {"account_id": 12, "email": "alice@acme.example", "role": "member", "joined_at": 1790380800}
]

To change someone’s role, an Owner sends PATCH /v1/organizations/{id}/members/{account_id} with a body of {"role": "owner"} or {"role": "member"}. To remove someone, an Owner sends DELETE to the same path. Any Member can leave by sending DELETE with their own account_id.

Changing Members takes a signed-in session. An API key can list Members but can’t change them, so nobody can use a leaked key to add themselves to your Organization.

An Organization always has at least one Owner. If you’re the last one, you have to make someone else an Owner before you can step down or leave.

When someone leaves, the API keys they made keep working, because the keys belong to the Organization. Revoke them separately if you need to.

Invite someone

To add a teammate, an Owner invites their email address from the Members page. Switchboard doesn’t send email. You get a link, and you send it to them yourself, in Slack or wherever your team talks. The link is shown once, works once, and expires after 7 days.

The dashboard creates the Invitation by sending POST /v1/organizations/{id}/invitations with your signed-in session and a body like {"email": "alice@acme.example", "role": "member"}. The response includes the link to send:

{
  "id": "3f9c1a2b7d4e",
  "organization_id": 4,
  "email": "alice@acme.example",
  "role": "member",
  "created_at": 1790294400,
  "expires_at": 1790899200,
  "secret": "sbi_mR3x9Qe2vT8wY1zA4bC7dF0gH5jK6lN2pS8uV3xZ1q",
  "link": "https://app.caprid.com/app/invitations/sbi_mR3x9Qe2vT8wY1zA4bC7dF0gH5jK6lN2pS8uV3xZ1q"
}

Only an Account with the invited email can accept, so a link forwarded to the wrong person is no use to them. When Alice opens the link, she signs in, or signs up, as alice@acme.example, and joins with the role you picked. If she signs up from the Invitation, she joins your Organization instead of creating her own, so she doesn’t need to pick a Namespace.

On app.caprid.com, WorkOS verifies every email address, so Alice doesn’t need the link at all. The first time she signs in, the dashboard offers to let her join Acme, next to the option to create her own Organization.

Owners can see pending Invitations on the Members page, or by sending GET to the same path. To revoke one, which stops its link working, send DELETE /v1/organizations/{id}/invitations/{id}.

As with Members, an API key can’t invite anyone or see Invitations, so nobody can use a leaked key to let someone in.