Create Tenant

POST/projects/{projectId}/tenants

Base URL: https://api.tinkermode.com

Create a new tenant in a multi-tenant project. This will create a new home with tenant information, a tenant root entity, and appropriate access control groups and permissions.

Prerequisites:

  • The project must have multi-tenancy enabled
  • The 'tenant_root' entity class must exist in the project
  • The specified agency admin access control group must exist and belong to the project

Required Permissions:

  • Permission to create homes.
  • Permission to create entities.
  • Permission to create access control groups.
  • Permission to manage the specified agency admin access control group permissions.

Authentication

Send an Authorization header of the form ModeCloud <AUTH_CODE>.

Must contain a user API key of a user with tenant creation permissions, a service account token with the same permission, or a project API key with admin permissions.

Path parameters

NameTypeRequiredConstraintsDescription
projectIdintegerYesThe unique ID for a specified project.

Request body

Content type: application/json

PropertyTypeRequiredConstraintsDescription
namestringYesDisplay name of the tenant. This will be used as the name for the tenant's home.
tenantobjectYesTenant-specific configuration.
Properties of tenant
PropertyTypeRequiredConstraintsDescription
agencyAdminAccessControlGroupIdintegerYesmin: 1ID of the existing access control group that will serve as the agency admin for this tenant. This group will have permissions to manage the tenant's resources.
identifierstringYespattern: ^[a-z0-9-]+$Unique identifier for the tenant within the project. Must be URL-safe and contain only lowercase letters, numbers, and hyphens. Cannot contain spaces.
timeZonestringYesTime zone for the tenant's root entity. This should be a time zone name defined in the IANA TZ Database.

Request example

{
  "name": "Acme Corporation Site 1",
  "tenant": {
    "agencyAdminAccessControlGroupId": 123,
    "identifier": "acme-corp-site-1"
  },
  "timeZone": "America/New_York"
}

Responses

201 Successful creation of tenant. Returns the created home with tenant information.

Content type: application/json

PropertyTypeRequiredConstraintsDescription
creationTimestringNoread-only (server-generated); format: date-timeTimestamp of home creation.
deactivatedbooleanNoTrue if home has been deactivated by project admin.
idintegerYesread-only (server-generated)Unique ID assigned at time of creation.
namestringYesDisplay name of home.
projectIdintegerYesread-only (server-generated)Project that this home belongs to.
tenantobjectNoTenant information associated with a home.
Properties of tenant
PropertyTypeRequiredConstraintsDescription
agencyAdminAccessControlGroupIdintegerYesread-only (server-generated)ID of the access control group that serves as the agency admin for this tenant.
identifierstringYesread-only (server-generated)Unique identifier for the tenant within the project.
tenantAdminAccessControlGroupIdintegerYesread-only (server-generated)ID of the access control group that serves as the tenant admin for this tenant.

Response example

{
  "creationTime": "2024-01-15T10:30:00Z",
  "deactivated": false,
  "id": 456,
  "name": "Acme Corporation Site 1",
  "projectId": 789,
  "tenant": {
    "agencyAdminAccessControlGroupId": 123,
    "identifier": "acme-corp-site-1",
    "tenantAdminAccessControlGroupId": 124
  }
}

401 Authorization is required to access this resource.

403 Request failed because of invalid data or denied permission.

Content type: application/json

PropertyTypeRequiredConstraintsDescription
dataobjectNoread-only (server-generated)Any relevant data related to error.
reasonstringYesread-only (server-generated)Reason of error.

429 Request failed because of rate limit.

Content type: application/json

PropertyTypeRequiredConstraintsDescription
dataobjectNoread-only (server-generated)Any relevant data related to error.
reasonstringYesread-only (server-generated)Reason of error.

500 An unexpected error has occurred.

Content type: application/json

PropertyTypeRequiredConstraintsDescription
dataobjectNoread-only (server-generated)Any relevant data related to error.
reasonstringYesread-only (server-generated)Reason of error.

503 The service is temporarily unavailable.

Content type: application/json

PropertyTypeRequiredConstraintsDescription
dataobjectNoread-only (server-generated)Any relevant data related to error.
reasonstringYesread-only (server-generated)Reason of error.