On This Page
> resources > docs > api > API Reference: Organizations

API Reference: Organizations

warning

Deleting a tenant will permanently remove all its processes, datasets, and user assignments. This action cannot be undone. You cannot delete the tenant you are using to authenticate.

warning

Removing a user from the organization will revoke their access to all tenants within the organization.

Organizations group multiple tenants together under a single entity.

Get the organization for the tenant

Readable with a tenant-scoped API key; an organization-scoped key is accepted as well.

Endpoint: GET /v1/tenant/{tenantId}/organization

Auth: Tenant- or organization-scoped API key · read scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid

Response (200):

Organization details

{
	"id": "00000000-0000-0000-0000-000000000000",
	"displayName": "string",
	"createdAt": "2024-03-15T16:30:00Z",
	"contactEmail": "string",
	"isActive": true,
	"allowedLogins": {
		"Microsoft": true,
		"Google": true,
		"LinkedIn": true
	},
	"createdBy": "00000000-0000-0000-0000-000000000000"
}
Field Type Required Description
id string Yes Format: uuid
displayName string Yes Default: ""
Max length: 128
createdAt string Yes Format: date-time
contactEmail string Yes Format: email
isActive boolean Yes Default: true
allowedLogins object Yes
createdBy string Yes Format: uuid

Errors:

  • 401 Missing, invalid, disabled or expired API key
  • 404 Resource not found

Get the organization’s seat capacity and auto-sync policy

Returns the org-wide purchased vs in-use seats per rung (Process Foundation, Process Architecture, Process Intelligence), the free-viewer allowance, the auto-sync target, the seat-drift explainer (what the engine will do and when), the billing interval and the externalApiSeatPolicy. Readable with a tenant-scoped API key. The {tenantId} path parameter is the context tenant (the organization of the organization-scoped key), not the target of the operation.

Endpoint: GET /v1/tenant/{tenantId}/organization/billing/seats

Auth: Tenant- or organization-scoped API key · read scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid

Response (200):

Seat capacity

{
	"contractType": "free",
	"isTrial": true,
	"purchased": {
		"foundation": 0,
		"architecture": 0,
		"intelligence": 0
	},
	"inUseBillable": {
		"foundation": 0,
		"architecture": 0,
		"intelligence": 0
	},
	"inUseFree": 0,
	"inUseDashboardViewers": 0,
	"totalBillable": 0,
	"freeViewerAllowance": 0,
	"freeViewerOverAllowance": 0,
	"dashboardViewerAllowance": 0,
	"dashboardViewerOverAllowance": 0,
	"fixedOverage": 0,
	"target": {
		"foundation": 0,
		"architecture": 0,
		"intelligence": 0
	},
	"drift": [
		{
			"rung": "foundation",
			"paid": 0,
			"actual": 0,
			"state": "equal",
			"buffer": 0
		}
	],
	"interval": "month",
	"nextBilledAt": "string",
	"externalApiSeatPolicy": "autoBill"
}
Field Type Required Description
contractType free | selfServe | fixed | unlimited Yes Allowed values: free, selfServe, fixed, unlimited
isTrial boolean Yes
purchased object Yes
inUseBillable object Yes
inUseFree number Yes
inUseDashboardViewers number Yes
totalBillable number Yes
freeViewerAllowance number Yes
freeViewerOverAllowance number Yes
dashboardViewerAllowance number Yes
dashboardViewerOverAllowance number Yes
fixedOverage number Yes
target object Yes
drift object[] Yes
interval month | year Yes Allowed values: month, year
nextBilledAt string Yes
externalApiSeatPolicy autoBill | requireCapacity Yes Allowed values: autoBill, requireCapacity

Errors:

  • 401 Missing, invalid, disabled or expired API key
  • 404 Resource not found

Get organization-wide statistics

The {tenantId} path parameter is the context tenant (the organization of the organization-scoped key), not the target of the operation.

Endpoint: GET /v1/tenant/{tenantId}/organization/statistics

Auth: Organization-scoped API key · read scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid

Response (200):

Organization statistics

{
	"userCount": 0,
	"tenantCount": 0,
	"tenantStatistics": [
		{
			"tenantId": "00000000-0000-0000-0000-000000000000",
			"uploadedDataSize": 0,
			"uploadedDataCount": 0,
			"modelCount": 0,
			"simulationCount": 0,
			"userCount": 0
		}
	]
}
Field Type Required Description
userCount number Yes
tenantCount number Yes
tenantStatistics object[] Yes

Errors:

  • 401 Missing, invalid, disabled or expired API key

List all tenants in the organization

The {tenantId} path parameter is the context tenant (the organization of the organization-scoped key), not the target of the operation.

Endpoint: GET /v1/tenant/{tenantId}/organization/tenants

Auth: Organization-scoped API key · read scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid
limit integer query No Maximum number of items to return
offset integer query No Number of items to skip

Response (200):

List of tenants

[
	{
		"id": "00000000-0000-0000-0000-000000000000",
		"createdBy": "00000000-0000-0000-0000-000000000000",
		"createdAt": "2024-03-15T16:30:00Z",
		"displayName": "string",
		"contactEmail": "string",
		"isActive": true,
		"shortName": "string",
		"useOrganizationTheme": true,
		"description": "string",
		"organizationId": "00000000-0000-0000-0000-000000000000",
		"allowedLogins": {
			"Microsoft": true,
			"Google": true,
			"LinkedIn": true
		},
		"tenantType": "normal",
		"url": "string"
	}
]

Errors:

  • 401 Missing, invalid, disabled or expired API key

Create a new tenant in the organization (requires an organization-scoped API key)

The {tenantId} path parameter is the context tenant (the organization of the organization-scoped key), not the target of the operation.

Endpoint: POST /v1/tenant/{tenantId}/organization/tenants

Auth: Organization-scoped API key · write scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid

Request Body:

{
	"displayName": "string",
	"shortName": "string",
	"description": "string",
	"timezone": "string",
	"tenantType": "normal"
}
Field Type Required Description
displayName string No Max length: 128
shortName string Yes
description string No Max length: 200
timezone string No Max length: 64
tenantType normal | sandbox | demo No Allowed values: normal, sandbox, demo

Response (201):

Tenant created

{
	"id": "00000000-0000-0000-0000-000000000000",
	"createdBy": "00000000-0000-0000-0000-000000000000",
	"createdAt": "2024-03-15T16:30:00Z",
	"displayName": "string",
	"contactEmail": "string",
	"isActive": true,
	"shortName": "string",
	"useOrganizationTheme": true,
	"description": "string",
	"organizationId": "00000000-0000-0000-0000-000000000000",
	"allowedLogins": {
		"Microsoft": true,
		"Google": true,
		"LinkedIn": true
	},
	"tenantType": "normal",
	"url": "string"
}
Field Type Required Description
id string Yes Format: uuid
createdBy string Yes Format: uuid
createdAt string Yes Format: date-time
displayName string Yes Default: ""
Max length: 128
contactEmail string Yes Format: email
isActive boolean Yes Default: true
shortName string Yes
useOrganizationTheme boolean Yes Default: true
description string Yes Max length: 200
organizationId string Yes Format: uuid
allowedLogins object Yes
tenantType normal | sandbox | demo Yes Allowed values: normal, sandbox, demo
Default: normal
url string Yes Format: uri

Errors:

  • 400 Bad request: e.g. an invalid filter expression, a process without a model, an unsupported upload type or a missing required field
  • 401 Missing, invalid, disabled or expired API key
  • 403 API key lacks the required scope or organization access, the tenant is inactive, or the plan blocks the file type
  • 406 The value cannot be accepted (e.g. a reserved or duplicate short name)

Soft-delete a tenant in the organization (requires an organization-scoped API key)

API access for the tenant stops immediately. The tenant and its data are kept during the deletion-safety window and are removed by the automated full delete afterwards. The tenant you are currently using (the context tenant) cannot be deleted.

Endpoint: DELETE /v1/tenant/{tenantId}/organization/tenants/{targetId}

Auth: Organization-scoped API key · write scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid
targetId string path Yes Format: uuid

Response (200):

Tenant deleted

{
	"success": true,
	"message": "string"
}
Field Type Required Description
success boolean Yes
message string Yes

Errors:

  • 400 Bad request: e.g. an invalid filter expression, a process without a model, an unsupported upload type or a missing required field
  • 401 Missing, invalid, disabled or expired API key
  • 403 API key lacks the required scope or organization access, the tenant is inactive, or the plan blocks the file type
  • 404 Resource not found

Restore a soft-deleted tenant in the organization (requires an organization-scoped API key)

Undo a soft delete inside the deletion-safety window: the tenant and its data come back exactly as they were and API access resumes. The {tenantId} path parameter is the context tenant (the organization of the organization-scoped key), not the target of the operation.

Endpoint: POST /v1/tenant/{tenantId}/organization/tenants/{targetId}/restore

Auth: Organization-scoped API key · write scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid
targetId string path Yes Format: uuid

Response (200):

Tenant restored

{
	"success": true,
	"message": "string"
}
Field Type Required Description
success boolean Yes
message string Yes

Errors:

  • 400 Bad request: e.g. an invalid filter expression, a process without a model, an unsupported upload type or a missing required field
  • 401 Missing, invalid, disabled or expired API key
  • 403 API key lacks the required scope or organization access, the tenant is inactive, or the plan blocks the file type
  • 404 Resource not found

List all users in the organization

The {tenantId} path parameter is the context tenant (the organization of the organization-scoped key), not the target of the operation.

Endpoint: GET /v1/tenant/{tenantId}/organization/users

Auth: Organization-scoped API key · read scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid
limit integer query No Maximum number of items to return
offset integer query No Number of items to skip

Response (200):

List of organization users

[
	{
		"id": "00000000-0000-0000-0000-000000000000",
		"email": "string",
		"firstName": "string",
		"lastName": "string",
		"createdAt": "2024-03-15T16:30:00Z",
		"lastLoginAt": "2024-03-15T16:30:00Z",
		"organizationId": "00000000-0000-0000-0000-000000000000",
		"isActiveInOrganization": true,
		"isAdminInOrganization": true
	}
]

Errors:

  • 401 Missing, invalid, disabled or expired API key

Update an organization user’s settings (requires an organization-scoped API key)

Role flags in the body (isAdminInOrganization, isActiveInOrganization) are honored verbatim; only issue organization-scoped keys to organization admins. The {tenantId} path parameter is the context tenant (the organization of the organization-scoped key), not the target of the operation.

Endpoint: PUT /v1/tenant/{tenantId}/organization/users/{userId}

Auth: Organization-scoped API key · write scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid
userId string path Yes Format: uuid

Request Body:

{
	"isActiveInOrganization": true,
	"isAdminInOrganization": true
}
Field Type Required Description
isActiveInOrganization boolean No Whether the user is active in the organization
isAdminInOrganization boolean No Organization admin rights (honored verbatim: only issue organization-scoped keys to org admins)

Response (200):

Updated

{
	"message": "string"
}
Field Type Required Description
message string Yes

Errors:

  • 401 Missing, invalid, disabled or expired API key
  • 403 API key lacks the required scope or organization access, the tenant is inactive, or the plan blocks the file type
  • 404 Resource not found

Remove a user from the organization (requires an organization-scoped API key)

The {tenantId} path parameter is the context tenant (the organization of the organization-scoped key), not the target of the operation.

Endpoint: DELETE /v1/tenant/{tenantId}/organization/users/{userId}

Auth: Organization-scoped API key · write scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid
userId string path Yes Format: uuid

Response (200):

User removed

{
	"message": "string"
}
Field Type Required Description
message string Yes

Errors:

  • 401 Missing, invalid, disabled or expired API key
  • 403 API key lacks the required scope or organization access, the tenant is inactive, or the plan blocks the file type
  • 404 Resource not found

Related Documentation

Design better processes. Build a connected architecture. Stay in control.

Get instant access with no credit card and no waiting. Turn the way your organization works into clear, connected process designs.

Build your process architecture, define ownership and controls, and align roles and responsibilities across every level.

Start your free trial and create one reliable foundation for governing, managing, and continuously improving your processes.

Get Your Free Trial Today