# Organisation

> Bootstrap a brand-new tenant.

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

> **WARNING:**
> No SDK wrapper. Issue via the [raw RPC envelope](/rpc/envelope-format).
> This is a one-shot — `BootstrapOrg` will refuse 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; routes default outbound trunks here. |
| `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 this returns successfully, the keypair 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. Hold the bootstrap secret somewhere short-lived (CI vault, HSM, or
   one-shot env var).
3. Call `BootstrapOrg` with the public half + a `kid` you choose.
4. Drop the bootstrap secret. It cannot be reused; the gateway burns it
   on success.
5. From now on, sign admin JWTs with the private half. The first thing
   most operators do is call [`PublishServiceAccount`](/admin/service-accounts)
   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` doesn't match any configured region.      |