# Tenant routes: invite, pin, provision, requestSetup

URL: /code/api/tenant/verbs · Id: `page:code/api/tenant/verbs`

> The Tenant Verbs invite, pin, provision, requestSetup as api.sb routes, with inputs, result, refusals and an example.

Reference for [Tenant](/business/nouns/tenant), one group of [Tenant routes](/code/api/tenant).

### Tenant.invite
Invite asks a Person to join a Customer’s Tenant, and resizes the Subscription when the Offer prices per member. [Verb page](/business/nouns/tenant/invite?interface=api).

```text
POST /{namespace}/tenants/{tenant}/invite
```

Path: `tenant`. Body, as JSON: the other inputs. Emits [`Tenant.invited`](/business/events/Tenant.invited).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `tenant` | [Tenant](/business/nouns/tenant) | Yes | The Customer’s Tenant. |
| `email` | `email` | Yes | Where the invitation goes. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `person` | [Person](/business/nouns/person) | Yes | The invited Person. |
| `tenant` | [Tenant](/business/nouns/tenant) | Yes | The Tenant the Person was invited to. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```bash
curl -X POST https://api.sb/leaseline.app/tenants/ten_Bu63f0he26/invite \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"dana@leaseline.app"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "person": {
    "$id": "https://api.sb/leaseline.app/people/person_oJZMe5UtCH",
    "$type": "Person",
    "name": "Dana Okafor"
  },
  "tenant": {
    "$id": "https://api.sb/leaseline.app/tenants/ten_Bu63f0he26",
    "$type": "Tenant",
    "placement": "path",
    "apiVersion": "v2"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Tenant.invite",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### Tenant.pin
Pin moves a Tenant’s keys to another API version, or to `latest`, once a call with its test key passes there. [Verb page](/business/nouns/tenant/pin?interface=api).

```text
POST /{namespace}/tenants/{tenant}/pin
```

Path: `tenant`. Body, as JSON: the other inputs. Emits [`Tenant.pinned`](/business/events/Tenant.pinned).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `tenant` | [Tenant](/business/nouns/tenant) | Yes | The Tenant whose keys move. |
| `apiVersion` | `string` | Yes | The version to answer at, such as `v2`, or `latest` to track the newest. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `tenant` | [Tenant](/business/nouns/tenant) | Yes | The Tenant, answering at its new version. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
| Until a call with the Tenant’s test key succeeds at the target version | [`refused`](/code/api/errors/refused) | Clear what the check names, then call it again. | None. |

**Example**

```bash
curl -X POST https://api.sb/leaseline.app/tenants/ten_Bu63f0he26/pin \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiVersion":"v2"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "tenant": {
    "$id": "https://api.sb/leaseline.app/tenants/ten_Bu63f0he26",
    "$type": "Tenant",
    "placement": "path",
    "apiVersion": "v2"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Tenant.pin",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### Tenant.provision
Provision creates a Customer’s Tenant in a Startup’s App, holding that Customer’s records apart from every other. [Verb page](/business/nouns/tenant/provision?interface=api).

```text
POST /{namespace}/tenants/provision
```

Body, as JSON: the inputs. Emits [`Tenant.provisioned`](/business/events/Tenant.provisioned).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `customer` | [Customer](/business/nouns/customer) | Yes | The Customer the Tenant serves. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `tenant` | [Tenant](/business/nouns/tenant) | Yes | The new Tenant. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The operation is part of an Offer the caller has not accepted or paid for. | [`payment-required`](/code/api/errors/payment-required) | Accept the Offer named in the response, then retry the call. | [Offer.accept](/business/nouns/offer/accept) |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
| The record is not in a state that allows this Verb, so the call is refused. | [`refused`](/code/api/errors/refused) | Read the record, run the Verb that moves it to an allowed state, then retry. | None. |

**Example**

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

```json
{
  "api": "https://api.sb/leaseline.app",
  "tenant": {
    "$id": "https://api.sb/leaseline.app/tenants/ten_Bu63f0he26",
    "$type": "Tenant",
    "placement": "path",
    "apiVersion": "v2"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Tenant.provision",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### Tenant.requestSetup
RequestSetup sends a Customer’s admin a link to connect their own sign-in, directory or verified domain to the Tenant. [Verb page](/business/nouns/tenant/request-setup?interface=api).

```text
POST /{namespace}/tenants/{tenant}/requestSetup
```

Path: `tenant`. Body, as JSON: the other inputs. Emits [`Tenant.setupRequested`](/business/events/Tenant.setupRequested).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `tenant` | [Tenant](/business/nouns/tenant) | Yes | The Tenant to set up. |
| `admin` | [Person](/business/nouns/person) | Yes | The Customer’s admin who receives the link. |
| `intent` | `string` | Yes | What the link sets up. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `link` | `url` | Yes | The single-use setup link, valid for 7 days. |
| `tenant` | [Tenant](/business/nouns/tenant) | Yes | The Tenant being set up. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```bash
curl -X POST https://api.sb/leaseline.app/tenants/ten_Bu63f0he26/requestSetup \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"admin":"person_sLqbXbW683","intent":"sso"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "link": "https://leaseline.app",
  "tenant": {
    "$id": "https://api.sb/leaseline.app/tenants/ten_Bu63f0he26",
    "$type": "Tenant",
    "placement": "path",
    "apiVersion": "v2"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Tenant.requestSetup",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```