Create a tenant
HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("http://localhost:8080/v2/tenants")) .header("Authorization", "Bearer <token>") .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString("{ \"tenantId\": \"t2\", \"name\": \"Second tenant\", \"quotas\": { \"jobsPerSec\": 100 }, \"limits\": { \"maxVariablesBytes\": 1048576 }, \"retention\": { \"recordRetentionMicros\": 604800000000 } }")) .build();HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());System.out.println(response.body());const url = 'http://localhost:8080/v2/tenants';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"tenantId":"t2","name":"Second tenant","quotas":{"jobsPerSec":100},"limits":{"maxVariablesBytes":1048576},"retention":{"recordRetentionMicros":604800000000}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:8080/v2/tenants \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "tenantId": "t2", "name": "Second tenant", "quotas": { "jobsPerSec": 100 }, "limits": { "maxVariablesBytes": 1048576 }, "retention": { "recordRetentionMicros": 604800000000 } }'Creates a tenant in the tenant registry and places it on a partition (Bundled and Cluster). It starts with no limits and 30 days of record retention unless quotas and retention name other values. Its registry entry, settings and admins are stored together or not at all. Sending the same request again (same tenantId, name, description, settings and admins) is safe: it completes a tenant an earlier attempt left unfinished and answers 201 with the tenant, as the first create does. A create for an existing tenant with other values answers 409. Needs tenant:admin on every tenant (the built-in admin or tenant-operator role in the starting tenant). Embedded serves one fixed tenant and answers 501.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters”Tenant selection. A principal bound to one tenant may omit it; if
sent, it must equal that tenant (403 otherwise). A principal that
may act in several tenants must send it on every request:
without it the request is refused with 400, and a tenant it may
not act in is refused with 403.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Required when creating.
Bundled and Cluster. Non-negative integers for activeInstanceLimit, createsPerSec, jobsPerSec, broadcastAdmission, timerArmRate, mailboxBound and feelBudget, and weight (at least 1, the tenant’s share of its partition’s engine time). Any other field is refused.
object
Bundled and Cluster. The tenant’s size limits; each only lowers what the engine itself accepts (4 MiB and 100 files per deployment, 32 MiB of variables per instance). A request or command over one is refused with 413 urn:bpm:error:tenant-limit-exceeded naming it; a change applies to the next request without a restart. Name only the fields to change.
object
Most bytes one deployment may hold, its files and their names together; 4194304 for a new tenant.
Most bytes of variables one process instance may hold, all its scopes together (the compact JSON of each value); 33554432 for a new tenant. A command that would grow an instance past it is refused; an instance that already holds more keeps running.
Most items one request may carry or ask for (jobs one activation hands out, files of a deployment or document upload, instructions of a modification or migration); 1000 for a new tenant.
Bundled and Cluster. How long the records of the tenant’s finished instances are kept.
object
In microseconds; 30 days (2592000000000) for a new tenant.
Users or clients made administrators of the tenant (members of it and of its built-in admin role), so they can work in it by naming it in X-Tenant-Id. Adds; never removes. The caller cannot name itself.
object
A username or identity-provider subject (USER), or an API client id or static token subject (CLIENT).
Example
{ "tenantId": "t2", "name": "Second tenant", "quotas": { "jobsPerSec": 100 }, "limits": { "maxVariablesBytes": 1048576 }, "retention": { "recordRetentionMicros": 604800000000 }}Responses
Section titled “ Responses ”Created, or the same request repeated.
object
The tenant’s quotas (Bundled and Cluster), or null.
The tenant’s size limits (Bundled and Cluster), or null.
object
The tenant’s record retention (Bundled and Cluster), or null.
object
Who is a member of the tenant.
object
Who holds the built-in admin role in the tenant.
object
How many of the tenant’s process instances are running now, call-activity children included (the count activeInstanceLimit bounds), as the reporting tables count them, so it can trail the engine by a moment (Bundled and Cluster); null in Embedded mode or when it cannot be read.
Example
{ "state": "ACTIVE"}The request is malformed, or it uses a property or filter this release does not support.
An RFC 9457 problem document. type is a stable TinyConductor URN.
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:invalid-argument", "title": "Bad Request", "status": 400, "detail": "entity key must be a positive int64 string", "instance": "/v2/process-instances/0"}No valid credential was presented.
An RFC 9457 problem document. type is a stable TinyConductor URN.
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:unauthorized", "title": "Unauthorized", "status": 401, "detail": "A valid bearer credential is required", "instance": "/v2/tenants"}Headers
Section titled “Headers”The caller lacks the required permission, a tenant named in the request is not the caller’s tenant, or a cookie write has no valid CSRF token.
An RFC 9457 problem document. type is a stable TinyConductor URN.
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:forbidden", "title": "Forbidden", "status": 403, "detail": "The principal lacks the action this route requires", "instance": "/v2/tenants"}An idempotency-key conflict, or a command the target’s current state does not allow.
An RFC 9457 problem document. type is a stable TinyConductor URN.
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:conflict", "title": "Conflict", "status": 409, "detail": "The idempotency key is already associated with another request", "instance": "/v2/tenants"}An internal failure. The details are never exposed.
An RFC 9457 problem document. type is a stable TinyConductor URN.
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:internal", "title": "Internal Server Error", "status": 500, "detail": "The request could not be completed", "instance": "/v2/tenants"}The operation is not offered in the engine’s current deployment mode.
An RFC 9457 problem document. type is a stable TinyConductor URN.
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:mode-not-supported", "title": "Mode Not Supported", "status": 501, "detail": "/v2/clock is not supported in bundled mode: the deterministic virtual clock and the storage-free reset exist only for the Embedded engine; Bundled and Cluster run on the system clock over durable history, which cannot be pinned, rewound or discarded", "instance": "/v2/clock", "mode": "bundled"}Backpressure, or a dependency is not ready. Retry with the same idempotency key.
An RFC 9457 problem document. type is a stable TinyConductor URN.
object
The request path.
Present only on mode-not-supported. It names the engine’s mode.
Example
{ "type": "urn:bpm:error:unavailable", "title": "Service Unavailable", "status": 503, "detail": "The required engine service is not ready", "instance": "/v2/tenants"}