# Tenant methods: invite, pin, provision, requestSetup

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

> The Tenant Verbs invite, pin, provision, requestSetup as typed SDK methods, with inputs, result, refusals and an example.

Reference for [Tenant](/business/nouns/tenant), one group of [Tenant methods](/code/sdk/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=sdk).

```ts
interface TenantVerbs {
  invite(input: TenantInviteInput, options?: SB.CallOptions): SB.Call<TenantInviteOutput>
}
```

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**

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

const { person, tenant } = await $.Tenant.invite({ tenant: 'ten_Bu63f0he26', email: 'dana@leaseline.app' })
```

### 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=sdk).

```ts
interface TenantVerbs {
  pin(input: TenantPinInput, options?: SB.CallOptions): SB.Call<Tenant>
}
```

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**

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

const tenant = await $.Tenant.pin({ tenant: 'ten_Bu63f0he26', apiVersion: 'v2' })
```

### 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=sdk).

```ts
interface TenantVerbs {
  provision(input: TenantProvisionInput, options?: SB.CallOptions): SB.Call<Tenant>
}
```

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**

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

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

### 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=sdk).

```ts
interface TenantVerbs {
  requestSetup(input: TenantRequestSetupInput, options?: SB.CallOptions): SB.Call<TenantRequestSetupOutput>
}
```

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**

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

const { link, tenant } = await $.Tenant.requestSetup({ tenant: 'ten_Bu63f0he26', admin: 'person_sLqbXbW683', intent: 'sso' })
```