# Tenant

URL: /business/nouns/tenant · Id: `noun:tenant`

> A Tenant is the partition of a Startup’s data that belongs to one Customer.

A Tenant is the partition of a [Startup](/business/nouns/startup)’s data that belongs to one [Customer](/business/nouns/customer).

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `placement` | `string` | No | Where the Tenant sits in an address: `path` or `host`. |
| `apiVersion` | `string` | No | The API version an unversioned call with this Tenant’s keys answers at; set at creation, moved only by `pin`. |

## Object
```json
{
  "$id": "https://api.sb/petpantry.shop/tenants/tenant_1",
  "$type": "Tenant",
  "placement": "path",
  "apiVersion": "v2"
}
```

## Relationships
- <a id="rel-admits"></a>A Tenant **admits** many [People](/business/nouns/person): a [Person](/business/nouns/person) joins a [Customer](/business/nouns/customer)’s Tenant as a member, and one Person can join many Tenants. `admits`, inverse [`joins`](/business/nouns/person#rel-joins).
- <a id="rel-api-keys"></a>A Tenant **has** many [API Keys](/business/nouns/api-key): every call it signs reads and writes only that [Customer](/business/nouns/customer)’s records. `apiKeys`, inverse [`reaches`](/business/nouns/api-key#rel-reaches).
- <a id="rel-hostnames"></a>A Tenant’s **hostnames** are many [Domains](/business/nouns/domain): a Tenant answers on the names its [Customer](/business/nouns/customer) connects; each such [Domain](/business/nouns/domain) serves one Tenant. `hostnames`, inverse [`serves`](/business/nouns/domain#rel-serves).
- <a id="rel-owned-by"></a>A Tenant **is owned by** one [Customer](/business/nouns/customer): each [Customer](/business/nouns/customer) has one Tenant: the partition of the [Startup](/business/nouns/startup)’s data that no other Customer reads. `ownedBy`, inverse [`owns`](/business/nouns/customer#rel-owns).
- <a id="rel-provisioned-by"></a>A Tenant **is provisioned by** many [Member Directories](/business/nouns/member-directory): a [Member Directory](/business/nouns/member-directory) fills and empties [Roles](/business/nouns/role) in one Tenant as people join and leave the [Customer](/business/nouns/customer). `provisionedBy`, inverse [`provisions`](/business/nouns/member-directory#rel-provisions).
- <a id="rel-signs-in-via"></a>A Tenant **signs in via** many [SSO Connections](/business/nouns/sso-connection): a Tenant’s people sign in through its [SSO Connections](/business/nouns/sso-connection); the [Customer](/business/nouns/customer)’s admin owns each one. `signsInVia`, inverse [`serves`](/business/nouns/sso-connection#rel-serves).
- <a id="rel-verifies"></a>A Tenant **verifies** many [Domains](/business/nouns/domain): a Tenant proves control of its [Customer](/business/nouns/customer)’s email domain, so sign-ins on that domain follow the Tenant’s policy. `verifies`, inverse [`verifiedBy`](/business/nouns/domain#rel-verified-by).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Tenant.invite](/business/nouns/tenant/invite) | Invite asks a Person to join a Customer’s Tenant, and resizes the Subscription when the Offer prices per member. | [Security Engineer](/agents/engineering/security-engineer) | [`Tenant.invited`](/business/events/Tenant.invited) | Two-way: `try`, `send`, `do` |
| [Tenant.pin](/business/nouns/tenant/pin) | Pin moves a Tenant’s keys to another API version, or to `latest`, once a call with its test key passes there. | [Customer](/business/nouns/customer) | [`Tenant.pinned`](/business/events/Tenant.pinned) | Two-way: `try`, `send`, `do` |
| [Tenant.provision](/business/nouns/tenant/provision) | Provision creates a Customer’s Tenant in a Startup’s App, holding that Customer’s records apart from every other. | [Integration Engineer](/agents/engineering/integration-engineer) | [`Tenant.provisioned`](/business/events/Tenant.provisioned) | None. |
| [Tenant.requestSetup](/business/nouns/tenant/request-setup) | RequestSetup sends a Customer’s admin a link to connect their own sign-in, directory or verified domain to the Tenant. | [Security Engineer](/agents/engineering/security-engineer) | [`Tenant.setupRequested`](/business/events/Tenant.setupRequested) | Two-way: `try`, `send`, `do` |
| <a id="create"></a>[Tenant.create](/business/nouns/tenant/create) | Creates a Tenant. Inherited from [Noun](/business/nouns/noun). | None. | `Tenant.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Tenant.get](/business/nouns/tenant/get) | Returns one Tenant by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Tenant.list](/business/nouns/tenant/list) | Returns Tenants, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Tenant.update](/business/nouns/tenant/update) | Changes the given properties of a Tenant. Inherited from [Noun](/business/nouns/noun). | None. | `Tenant.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Tenant.delete](/business/nouns/tenant/delete) | Deletes a Tenant; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Tenant.deleted` | One-way: `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Tenant.create` | Yes | Yes | Yes | No |
| `Tenant.get` | Yes | Yes | Yes | Yes |
| `Tenant.list` | Yes | Yes | Yes | Yes |
| `Tenant.update` | Yes | Yes | Yes | No |
| `Tenant.delete` | Yes | Yes | Yes | No |
| `Tenant.invite` | Yes | Yes | Yes | No |
| `Tenant.pin` | Yes | Yes | Yes | No |
| `Tenant.provision` | Yes | Yes | Yes | No |
| `Tenant.requestSetup` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Provision the latest tenant with a customer.
```

**API**

```bash
curl -X POST https://api.sb/routewise.dev/tenants/provision \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer":"customer_1"}'
```

```json
{
  "api": "https://api.sb/routewise.dev",
  "tenant": {
    "$id": "https://api.sb/routewise.dev/tenants/tenant_1",
    "$type": "Tenant",
    "placement": "path",
    "apiVersion": "v2"
  },
  "action": {
    "$id": "https://api.sb/routewise.dev/actions/action_1",
    "operation": "Tenant.provision",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/routewise.dev/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const tenant = await $.Tenant.provision({ customer: 'customer_1' })
```

**CLI**

```bash
npx startup-builder do Tenant.provision --json '{"customer":"customer_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Tenant.provision({ customer: 'customer_1' })"
  }
}
```

## Example
A recruiting agency's Tenant in a candidate-tracking [SaaS](/products/templates/saas) holds its 40,000 candidates, its API keys, and its usage. No other [Customer](/business/nouns/customer) reads it.