API Reference: Tenants

Get tenant information

Endpoint: GET /v1/tenant/{tenantId}

Auth: Tenant-scoped API key · read scope

Parameters:

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

Response (200):

Tenant details

{
	"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:

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

Update tenant settings

Endpoint: PUT /v1/tenant/{tenantId}

Auth: Tenant-scoped API key · write scope

Parameters:

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

Request Body:

{
	"id": "00000000-0000-0000-0000-000000000000",
	"displayName": "string",
	"contactEmail": "string",
	"shortName": "string",
	"description": "string"
}

Field	Type	Required	Description
id	string	No	Format: uuid
displayName	string	No
contactEmail	string	No
shortName	string	No
description	string	No

Response (200):

Updated tenant

{
	"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)

Get tenant statistics (data size, models, simulations, users)

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

Auth: Tenant-scoped API key · read scope

Parameters:

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

Response (200):

Tenant statistics

{
	"tenantId": "00000000-0000-0000-0000-000000000000",
	"uploadedDataSize": 0,
	"uploadedDataCount": 0,
	"modelCount": 0,
	"simulationCount": 0,
	"userCount": 0
}

Field	Type	Required	Description
tenantId	string	Yes	Format: uuid
uploadedDataSize	number	Yes
uploadedDataCount	number	Yes
modelCount	number	Yes
simulationCount	number	Yes
userCount	number	Yes

Errors:

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

List users in the tenant

Returns the matching users as a bare JSON array: there is no total count; page with limit/offset.

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

Auth: Tenant-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 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",
		"tenantId": "00000000-0000-0000-0000-000000000000",
		"isActiveInTenant": true,
		"isAdminInTenant": true,
		"access": "none",
		"isDashboardViewer": true,
		"organizationId": "00000000-0000-0000-0000-000000000000",
		"isActiveInOrganization": true,
		"isAdminInOrganization": true
	}
]

Errors:

• 401 Missing, invalid, disabled or expired API key

Add a user to the tenant (no invitation email is sent)

Role fields in the body (isAdminInTenant, access: none|portalViewer|designer|architect|intelligence, isDashboardViewer) are honored verbatim; this endpoint is a full tenant-admin surface, so only issue write-scoped keys to trusted callers. Dashboard viewing is the isDashboardViewer boolean; the legacy read-only viewer rung has been removed.

Endpoint: POST /v1/tenant/{tenantId}/users

Auth: Tenant-scoped API key · write scope

Parameters:

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

Request Body:

{
	"email": "string",
	"firstName": "string",
	"lastName": "string",
	"isActiveInTenant": true,
	"isAdminInTenant": true,
	"access": "none",
	"isDashboardViewer": true,
	"preferredLocale": "en"
}

Field	Type	Required	Description
email	string	Yes	The user’s email address (also the login identity) Format: email
firstName	string	No	Optional first name Max length: 64
lastName	string	No	Optional last name Max length: 64
isActiveInTenant	boolean	No	Whether the user is active in this tenant
isAdminInTenant	boolean	No	Admin rights in this tenant (honored verbatim: full tenant-admin surface)
access	none | portalViewer | designer | architect | intelligence	No	Single-select seat: none | portalViewer | designer | architect | intelligence Allowed values: none, portalViewer, designer, architect, intelligence
isDashboardViewer	boolean	No	Whether the user has read-only dashboard view
preferredLocale	en | zh | es | fr | de | pt | it | nl | ja | tr	No	Preferred UI locale for the user Allowed values: en, zh, es, fr, de, pt, it, nl, ja, tr

Response (201):

User added

{
	"id": "string",
	"message": "string"
}

Field	Type	Required	Description
id	string	Yes	The id of the newly added user
message	string	Yes

Errors:

• 401 Missing, invalid, disabled or expired API key
• 409 The request conflicts with the current state (e.g. a seat gate or a reused id)

Update a user’s tenant settings

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

Auth: Tenant-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:

{
	"isActiveInTenant": true,
	"isAdminInTenant": true,
	"access": "none",
	"isDashboardViewer": true
}

Field	Type	Required	Description
isActiveInTenant	boolean	No	Whether the user is active in this tenant
isAdminInTenant	boolean	No	Admin rights in this tenant (honored verbatim: full tenant-admin surface)
access	none | portalViewer | designer | architect | intelligence	No	Single-select seat: none | portalViewer | designer | architect | intelligence. Dashboard viewing is the isDashboardViewer boolean. Allowed values: none, portalViewer, designer, architect, intelligence
isDashboardViewer	boolean	No	Whether the user has read-only dashboard view

Response (200):

Updated

{
	"message": "string"
}

Field	Type	Required	Description
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
• 404 Resource not found

Remove a user from the tenant

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

Auth: Tenant-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:

• 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
• 404 Resource not found

Mint a one-time login handoff token for a user

Returns a single-use token (60s TTL) bound to the user, tenant and organization, plus the url to send the user’s browser to. Open the URL in the user’s browser and they land in ProcessMind already authenticated: no email link, no impersonation; the user gets their own session. Requires the dedicated sessions scope on the API key: an organization-scoped key may mint for any tenant of its organization, a tenant-scoped key only for users of its own tenant. Treat the token as password-equivalent: it is returned once, never logged, and revoked by disabling the key or the user.

Endpoint: POST /v1/tenant/{tenantId}/users/{userId}/login-token

Auth: Tenant- or organization-scoped API key · sessions scope · rate limit 2 req/s (burst 4)

Parameters:

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

Request Body:

Optional landing path (relative app path, e.g. “app” or “app/dashboards”)

{
	"path": "string"
}

Field	Type	Required	Description
path	string	No	Max length: 512

Response (200):

Login handoff token

{
	"token": "string",
	"url": "string",
	"expiresInSeconds": 0,
	"expiresAt": "2024-03-15T16:30:00Z"
}

Field	Type	Required	Description
token	string	Yes
url	string	Yes
expiresInSeconds	number	Yes
expiresAt	string	Yes	Format: date-time

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
• 429 Rate limited: see the endpoint’s documented rate limit

API keys authenticate your integrations. Organization-scoped keys can provision and manage the keys of any tenant in the organization.

List the tenant’s API keys

Requires an organization-scoped API key. The secret is never returned.

Endpoint: GET /v1/tenant/{tenantId}/api-keys

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 API keys

[
	{
		"id": "00000000-0000-0000-0000-000000000000",
		"tenantId": "00000000-0000-0000-0000-000000000000",
		"organizationId": "00000000-0000-0000-0000-000000000000",
		"displayName": "string",
		"partialKey": "string",
		"enabled": true,
		"createdAt": "2024-03-15T16:30:00Z",
		"lastUsedAt": "2024-03-15T16:30:00Z",
		"expiresAt": "2024-03-15T16:30:00Z",
		"scope": {
			"read": true,
			"write": true,
			"uploadData": true,
			"sessions": true
		}
	}
]

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

Create a tenant-scoped API key

Requires an organization-scoped write key. The secret is generated server-side and returned exactly once in the response; store it safely. Only its hash is kept.

Endpoint: POST /v1/tenant/{tenantId}/api-keys

Auth: Organization-scoped API key · write scope

Parameters:

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

Request Body:

{
	"displayName": "string",
	"scope": {
		"read": true,
		"write": true,
		"uploadData": true,
		"sessions": true
	},
	"enabled": true,
	"expiresAt": "2024-03-15T16:30:00Z"
}

Field	Type	Required	Description
displayName	string	Yes	Max length: 128
scope	object	No
enabled	boolean	No
expiresAt	string	No	Format: date-time

Response (201):

API key created (includes the one-time secret)

{
	"id": "00000000-0000-0000-0000-000000000000",
	"tenantId": "00000000-0000-0000-0000-000000000000",
	"organizationId": "00000000-0000-0000-0000-000000000000",
	"displayName": "string",
	"partialKey": "string",
	"enabled": true,
	"createdAt": "2024-03-15T16:30:00Z",
	"lastUsedAt": "2024-03-15T16:30:00Z",
	"expiresAt": "2024-03-15T16:30:00Z",
	"scope": {
		"read": true,
		"write": true,
		"uploadData": true,
		"sessions": true
	},
	"secret": "string"
}

Field	Type	Required	Description
id	string	Yes	Format: uuid
tenantId	string	Yes	Format: uuid
organizationId	string	Yes	Format: uuid
displayName	string	Yes	Max length: 128
partialKey	string	Yes	Max length: 128
enabled	boolean	Yes	Default: true
createdAt	string	Yes	Format: date-time
lastUsedAt	string	Yes	Format: date-time
expiresAt	string	Yes	Format: date-time
scope	object	Yes
secret	string	Yes	Max length: 128

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

Update a tenant-scoped API key

Requires an organization-scoped write key. Scope fields are merged with the stored scope.

Endpoint: PUT /v1/tenant/{tenantId}/api-keys/{keyId}

Auth: Organization-scoped API key · write scope

Parameters:

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

Request Body:

{
	"displayName": "string",
	"scope": {
		"read": true,
		"write": true,
		"uploadData": true,
		"sessions": true
	},
	"enabled": true,
	"expiresAt": "2024-03-15T16:30:00Z"
}

Field	Type	Required	Description
displayName	string	No	Max length: 128
scope	object	No
enabled	boolean	No
expiresAt	string	No	Format: date-time

Response (200):

API key updated

{
	"id": "00000000-0000-0000-0000-000000000000",
	"tenantId": "00000000-0000-0000-0000-000000000000",
	"organizationId": "00000000-0000-0000-0000-000000000000",
	"displayName": "string",
	"partialKey": "string",
	"enabled": true,
	"createdAt": "2024-03-15T16:30:00Z",
	"lastUsedAt": "2024-03-15T16:30:00Z",
	"expiresAt": "2024-03-15T16:30:00Z",
	"scope": {
		"read": true,
		"write": true,
		"uploadData": true,
		"sessions": true
	}
}

Field	Type	Required	Description
id	string	Yes	Format: uuid
tenantId	string	Yes	Format: uuid
organizationId	string	Yes	Format: uuid
displayName	string	Yes	Max length: 128
partialKey	string	Yes	Max length: 128
enabled	boolean	Yes	Default: true
createdAt	string	Yes	Format: date-time
lastUsedAt	string	Yes	Format: date-time
expiresAt	string	Yes	Format: date-time
scope	object	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

Delete a tenant-scoped API key

Requires an organization-scoped write key. The key is soft-deleted and stops authenticating immediately.

Endpoint: DELETE /v1/tenant/{tenantId}/api-keys/{keyId}

Auth: Organization-scoped API key · write scope

Parameters:

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

Response (200):

API key deleted

{
	"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