Skip to main content
POST
Provision a tenant

Authorizations

Authorization
string
header
required

A machine-client token from POST /v1/auth/client-token. Reads need the pulse.read scope; provisioning and tenant updates need pulse.write, which the token only carries when requested_scopes asks for it. Creating, changing, disabling and resetting MFA for users, and the tenant sign-in policy, need a signed-in user's token instead: they reject API-key tokens.

Body

application/json

Creates a tenant under parent_tenant_id and queues the job that deploys it. The response carries the new tenant_id and a job_id; poll Get a provisioning job's status (GET /v1/msp/provisioning/jobs/{jobId}) until the job reaches deployed.

Only parent_tenant_id, name and trial are required. Validation failures return 400 with the offending field names as keys, for example {"industry_id": ["unsupported"]}.

parent_tenant_id
string<uuid>
required

The tenant the new tenant is created under. It must be your own tenant or one of its descendants; any other tenant returns 401. Use tenant_id from List tenants (GET /v1/msp/admin/tenants).

name
string
required

The name of the tenant. Leading and trailing spaces are trimmed; a blank name returns 400 invalid_provisioning_request.

trial
boolean
required

When true, creates a 21-day trial tenant.

short_name
null | string

A short display name for the tenant, at most 70 characters. A longer value returns 400 with short_name: ["maximum_length_70"].

kind
null | enum<string>

Tenant kind.

Allowed values: organization | tenant. Defaults to tenant.

Available options:
organization,
tenant
contact
null | string

The tenant's primary contact.

notification_email
null | string

The email address that receives notifications for this tenant.

address_1
null | string

First line of the tenant's street address.

address_2
null | string

Second line of the tenant's street address.

city
null | string

The tenant's city.

state
null | string

The tenant's state, province or region.

postal_code
null | string

The tenant's postal or ZIP code.

country_id

The tenant's country. Use id from List countries (GET /v1/msp/admin/lookups/countries).

The country also decides where the tenant is hosted and its data is stored. When it is omitted, the tenant is hosted in the same region as its parent.

industry_id

The tenant's industry. Use id from List industries (GET /v1/msp/admin/lookups/industries). An unknown id returns 400 with industry_id: ["unsupported"].

employee_count

The number of employees at the tenant. Defaults to 1.

assigned_technician_user_id
null | string<uuid>

The technician responsible for this tenant. Use user_id from List technicians who can be assigned to a tenant (GET /v1/msp/provisioning/eligible-technicians?parent_tenant_id=…), called with the same parent_tenant_id. Anyone else returns 400 with assigned_technician_user_id: ["ineligible"].

tenant_type_id

Represents the tenant type, which can be obtained from List tenant types (GET /v1/msp/admin/lookups/tenant-types); send its id.

Allowed values:

  • 0 for MSP
  • 1 for MSSP
  • 2 for Reseller
  • 3 for Client

Any other value returns 400 with tenant_type_id: ["unsupported"].

support_enabled
null | boolean

Support enabled for tenant. Defaults to true.

idempotency_key
null | string

A unique value, such as a UUID v4, that you generate for each tenant you create. Retrying a request with a key that was already accepted returns the original result instead of creating a second tenant, so a timed-out request is safe to retry. An Idempotency-Key header, when sent, takes precedence over this field.

Response

OK

A tenant lifecycle job, returned by Provision a tenant, Get a provisioning job's status and Decommission a tenant. Jobs run asynchronously: poll Get a provisioning job's status (GET /v1/msp/provisioning/jobs/{jobId}) with job_id until status is deployed (create), decommissioned (decommission) or failed.

tenant_id
string<uuid>
required

The tenant the job is for. After a create, use it as tenantId in the other endpoints.

tenant_number
required

The tenant's number, as shown to support staff.

job_id
string<uuid>
required

The job's id. Pass it to Get a provisioning job's status.

status
string
required

The job's status: queued | leased | running | deployed | decommissioned | failed.

  • queued: accepted, waiting for a worker. A new create or decommission always starts here.
  • leased / running: a worker has picked it up.
  • deployed: the tenant is ready and its status is now active.
  • decommissioned: the tenant is removed and its status is now deleted.
  • failed: the job did not complete.
tenant_host
string
required

The tenant's host name, for example cc4a1b2c.cyrisma.com.

registration_key
null | string
required

The tenant's agent registration key: 32 upper-case hexadecimal characters. Agents installed for this tenant register with it.

orchestrator_wake_succeeded
null | boolean
required

Internal. Always null in these responses; ignore it.