# Organisation

> Bootstrap a brand-new tenant.

`BootstrapOrg` is the first call that you make against a fresh
FirstByte deployment for a new tenant. It creates the tenant record
and mints the first admin service account. Every subsequent admin call
uses a JWT signed by that account.

> **WARNING:**
> There is no SDK wrapper. Use the [raw RPC envelope](/rpc/envelope-format).
> This is a one-shot call. `BootstrapOrg` refuses to run twice for the
> same `tenant_id`.

## `BootstrapOrg`

Request (`BootstrapOrgRequest`):

| Field             | Type     | Notes                                                |
| ----------------- | -------- | ---------------------------------------------------- |
| `bootstrap_secret`| `string` | Out-of-band secret distributed when the gateway was provisioned. *Not* a JWT. |
| `tenant_id`       | `string` | Stable id (lowercase, dash-separated).               |
| `display_name`    | `string` | Human-readable tenant name.                          |
| `region`          | `string` | One of the gateway's configured regions. Default outbound trunks route to this region. |
| `admin_public_key_pem` | `string` | RSA public half of the keypair you generated for this tenant. |
| `admin_private_key_id` | `string` | `kid` to associate with the public key.        |

Response (`BootstrapOrgResponse`):

| Field             | Type     | Notes                                            |
| ----------------- | -------- | ------------------------------------------------ |
| `status`          | `string` | `"ok"` or `"error"`.                             |
| `error_message`   | `string` | Populated on error.                              |
| `tenant_id`       | `string` | Echoed for confirmation.                         |
| `created_at_ms`   | `int64`  | Unix epoch ms.                                   |

After a successful response, the keypair that you supplied is the
**admin** service account for the tenant. Use the private half to sign
the `admin_token` for every subsequent admin call.

## Recommended flow

1. Generate an RSA-2048 keypair locally.
2. Keep the bootstrap secret in a short-lived store (CI vault, HSM, or
   one-shot env var).
3. Call `BootstrapOrg` with the public half and a `kid` that you choose.
4. Discard the bootstrap secret. You cannot use it again. The gateway
   burns it on success.
5. From now on, sign admin JWTs with the private half. Most operators
   then call [`PublishServiceAccount`](/admin/service-accounts) first,
   to create separate `"sdk"`-role keys for their applications.

## Failure modes

| `error_message` substring     | Cause                                              |
| ----------------------------- | -------------------------------------------------- |
| `bootstrap secret invalid`    | Wrong or already-consumed secret.                  |
| `tenant_id already exists`    | Bootstrap already completed for this id.           |
| `public_key_pem invalid`      | Not a valid PKCS#8/SPKI PEM RSA public key.        |
| `region unknown`              | `region` does not match a configured region.       |