# Core concepts

> Organizations, Namespaces, credentials, paths, tracks and relays, on one page.

URL: https://www.caprid.com/docs/getting-started/concepts/

The words below are used precisely everywhere in these docs. Each section links to where the
concept is defined in full.

## Who owns what

- **Organization**: A customer of Switchboard. It owns Namespaces, API keys and Self-hosted relays.
  People manage it as its **Members**, each signed in with their own **Account**. **Owners** can
  also delete Namespaces, invite people, remove Members, and change who is an Owner.
- **Namespace**: The first segment of every path you can sign for, owned by one Organization for
  good. If your Namespace is `acme`, everything you publish lives under `acme/`. The name is never
  reissued, even after it's deleted. Use one per environment: `acme` for prod, `acme-staging` for
  staging.

See [Organizations and Namespaces](https://www.caprid.com/docs/guides/organizations/) and
[Prod and staging](https://www.caprid.com/docs/guides/prod-and-staging/).

## Credentials

| Credential | Held by | For |
|---|---|---|
| **API key** (`sb_...`) | Your backend | Managing your Organization through the [Account API](https://www.caprid.com/docs/reference/http/account/) |
| **Signing key** (a JWK) | Your backend | Minting Client tokens without calling Switchboard |
| **Client token** (a JWT) | A publisher or viewer | Connecting to a relay |
| **Relay enrollment token** (`sbe_...`) | You, briefly | Enrolling a Self-hosted relay |
| **Node key** (`sbn_...`) | Your Self-hosted relay | Talking to Switchboard and its peers |

Only a Client token should ever reach a browser or an app. A Signing key's **scope** caps what
it can sign, and relays enforce that cap on every token. See [Credentials](https://www.caprid.com/docs/guides/credentials/).

## Paths and grants

A Client token has three claims that matter:

- `root`: the full path the token is anchored at, starting with your Namespace, like `acme/room/42`.
- `put`: prefixes under `root` it may publish to.
- `get`: prefixes under `root` it may subscribe to.

`""` means everything under `root`. Prefixes match whole path segments, so `live` covers
`live/cam1` but not `lively`. A Client passes the token to the relay as `?jwt=` on the URL it
connects to. See [Client tokens](https://www.caprid.com/docs/guides/credentials/#client-tokens).

When you call the API, paths are relative to the Namespace (`room/42`). Inside a token they're
written out in full (`acme/room/42`). See
[Paths in the API and in tokens](https://www.caprid.com/docs/guides/organizations/#paths-in-the-api-and-in-tokens).

## Tracks and objects

What a Client publishes and subscribes to, in the SDKs' terms:

- **Namespace (SDK)**: The ordered list of path fields a publisher connection serves, like
  `['run', '1']`. It's relative to the endpoint URL's path. Not to be confused with the Switchboard
  Namespace, which is only the first segment of the full path.
- **Track**: A named sequence of objects within a namespace, like `ticker` or `video`.
- **Object** and **group**: An object is one payload of bytes the SDK doesn't interpret. Objects are
  sent in groups. A plain `write` sends one object as its own group.
- **Announce**: A publisher announces its namespace so the relay can route subscriptions to it. A
  fresh namespace can briefly reject subscriptions (request error 16) while the announce
  propagates. Retry them.
- **Demand**: A publisher's `write` waits until the relay wants the track, which means a subscriber
  exists.

The [SDK vocabulary](https://www.caprid.com/docs/spec/vocabulary/) has every public name in both SDKs, and the
[behavior contract](https://www.caprid.com/docs/spec/behavior/) says exactly what each must do.

## Endpoints

A Client connects to a relay endpoint. The SDKs' `DEFAULT_ENDPOINT` is the hosted Relay,
`https://relay.mux.global`. Put your token's root in the endpoint's path
(`https://relay.mux.global/acme/room/42`) and name namespaces relative to it. The connection then
can't reach outside that root. `roomEndpoint(['acme', 'room', '42'])` (`room_endpoint` in Python)
builds that URL. Pass an endpoint first to root another relay. A Client that spans several rooms
under one grant can use the bare host instead, with namespaces that include the root. See [room-rooted endpoints](https://www.caprid.com/docs/spec/behavior/#room-rooted-endpoints).

## Relays

- **Platform relay**: A relay Mux runs. It may carry tracks from any Namespace. The Mux relays carry
  announcements between regions, so a publisher and a subscriber can each use their nearest relay.
- **Self-hosted relay**: A `moq-relay` you run and enroll in your Organization. It carries only your
  Organization's Namespaces. See [Running a Self-hosted relay](https://www.caprid.com/docs/guides/self-hosted-relays/).
- **Admission**: Switchboard deciding, for one relay, whether a session may start and with which
  grant. Relays ask through the [Relay plane API](https://www.caprid.com/docs/reference/http/relay/).