Skip to content
TinyConductorTinyConductorTinyConductor

Register an API client

POST
/v2/clients
curl --request POST \
  --url http://localhost:8080/v2/clients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "clientId": "worker", "name": "Payment worker" }'
Available inEmbeddedBundledCluster
AuthAuthenticated Bearer token or console session with X-CSRF-Token · requires identity:write

Registers an OAuth2 client-credentials client in the caller’s tenant and answers its secret once. Only an argon2id hash of the secret is kept. Client ids are unique across tenants (409).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters”
x-tenant-id
string
>= 1 characters

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”
Media typeapplication/json
object
clientId
required
string
name
string
expiresAt
string format: date-time
Example
{
  "clientId": "worker",
  "name": "Payment worker"
}

Responses

Section titled “ Responses ”

201

Section titled “201”

Created.

Media typeapplication/json
object
clientId
required
string
name
string | null
createdAt
required
string format: date-time
expiresAt
string | null format: date-time
lastUsedAt
string | null format: date-time
revokedAt
string | null format: date-time
secretRotatedAt
string | null format: date-time
clientSecret
required

Shown once. Only its argon2id hash is kept.

string
Examplegenerated
{
  "clientId": "example",
  "name": "example",
  "createdAt": "2026-04-15T12:00:00Z",
  "expiresAt": "2026-04-15T12:00:00Z",
  "lastUsedAt": "2026-04-15T12:00:00Z",
  "revokedAt": "2026-04-15T12:00:00Z",
  "secretRotatedAt": "2026-04-15T12:00:00Z",
  "clientSecret": "example"
}

400

Section titled “400”

The request is malformed, or it uses a property or filter this release does not support.

Media typeapplication/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object
type
required
string
/^urn:bpm:error:/
title
required
string
status
required
integer
>= 400 <= 599
detail
required
string
instance
required

The request path.

string
mode

Present only on mode-not-supported. It names the engine’s mode.

string
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"
}

401

Section titled “401”

No valid credential was presented.

Media typeapplication/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object
type
required
string
/^urn:bpm:error:/
title
required
string
status
required
integer
>= 400 <= 599
detail
required
string
instance
required

The request path.

string
mode

Present only on mode-not-supported. It names the engine’s mode.

string
Example
{
  "type": "urn:bpm:error:unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "A valid bearer credential is required",
  "instance": "/v2/clients"
}

Headers

Section titled “Headers”
WWW-Authenticate
string
Allowed value: Bearer

403

Section titled “403”

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.

Media typeapplication/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object
type
required
string
/^urn:bpm:error:/
title
required
string
status
required
integer
>= 400 <= 599
detail
required
string
instance
required

The request path.

string
mode

Present only on mode-not-supported. It names the engine’s mode.

string
Example
{
  "type": "urn:bpm:error:forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The principal lacks the action this route requires",
  "instance": "/v2/clients"
}

409

Section titled “409”

An idempotency-key conflict, or a command the target’s current state does not allow.

Media typeapplication/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object
type
required
string
/^urn:bpm:error:/
title
required
string
status
required
integer
>= 400 <= 599
detail
required
string
instance
required

The request path.

string
mode

Present only on mode-not-supported. It names the engine’s mode.

string
Example
{
  "type": "urn:bpm:error:conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "The idempotency key is already associated with another request",
  "instance": "/v2/clients"
}

500

Section titled “500”

An internal failure. The details are never exposed.

Media typeapplication/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object
type
required
string
/^urn:bpm:error:/
title
required
string
status
required
integer
>= 400 <= 599
detail
required
string
instance
required

The request path.

string
mode

Present only on mode-not-supported. It names the engine’s mode.

string
Example
{
  "type": "urn:bpm:error:internal",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "The request could not be completed",
  "instance": "/v2/clients"
}

503

Section titled “503”

Backpressure, or a dependency is not ready. Retry with the same idempotency key.

Media typeapplication/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object
type
required
string
/^urn:bpm:error:/
title
required
string
status
required
integer
>= 400 <= 599
detail
required
string
instance
required

The request path.

string
mode

Present only on mode-not-supported. It names the engine’s mode.

string
Example
{
  "type": "urn:bpm:error:unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "The required engine service is not ready",
  "instance": "/v2/clients"
}