Organization management API

These endpoints manage your organization’s automation clients and tenants. Use a human owner or admin bearer token and the public platform API origin. An automation client cannot call them, even to rotate its own credentials. The organization ID comes from the path; no workspace selection is needed for these organization-scoped operations.

For interactive administration, the Console and M2M CLI and tenant commands provide the same operations.

Machine clients

All paths below are relative to /v1/organizations/{organization_id}/m2m. {client_id} is the platform record ID (client.id), not the OAuth client_id returned for credential use. {credential_id} is a credential metadata ID.

Method	Path	Result
GET	base path	List {clients: [...]} without secrets.
GET	/profiles	Supported permission profiles, scopes, and catalog version.
POST	base path	Create a client and issue its first credential.
GET	/{client_id}	Inspect {client, credentials} without secrets.
PATCH	/{client_id}	Rename, change permissions, disable, or enable.
POST	/{client_id}/credentials	Add a credential for rotation.
DELETE	/{client_id}/credentials/{credential_id}	Revoke one credential.
DELETE	/{client_id}	Delete the client and withdraw access.

Create

Send Content-Type: application/json and an Idempotency-Key of 8–256 characters:

{
  "name": "production-deployer",
  "profile": "deploy",
  "expires_in_days": 90
}

description is optional. Use observe, invoke, or deploy, or set profile to custom with an array of supported scopes instead of a named profile. The default credential lifetime is 90 days and maximum 365.

A successful issue returns HTTP 201 with {client, credential, client_id, client_secret}. The secret is returned once and cannot be read later. Retrying with the same idempotency key cannot issue another secret; an already completed issue returns a conflict without disclosing it again. Do not log or cache the response. Inspect metadata and rotate if a response was lost.

Update

Fetch the client and send its current version with a PATCH:

{"version": 3, "name": "release-deployer", "profile": "deploy"}

To disable, send {"version": 3, "status": "disabled"} instead. Use active to re-enable. Do not combine a status transition with name or permission changes. A stale version conflicts; fetch the record again before deciding whether to retry.

Rotate and revoke

Credential creation also requires an Idempotency-Key and a non-empty label:

{"label": "September rotation", "expires_in_days": 90}

At most two live, unexpired credentials are allowed per client. Switch consumers to the new secret, then DELETE the old credential. At most 20 non-deleted clients are allowed per organization.

Updates can return 200 or 202; revocation and deletion can return 204 or 202. A 202 means cleanup or application of a change is still pending. Inspect the resource for progress. Client disable/delete and scope removal apply at the next platform authorization decision without waiting for token expiry. Revoking an individual credential prevents new token issuance once provider cleanup completes; already-issued tokens can remain valid until expiry. Disable the client if immediate withdrawal is required.

Machine management responses use Cache-Control: no-store. Mutations are rate-limited per organization and human actor; handle HTTP 429 with backoff. A conflict can indicate a changed version, lifecycle state, credential limit, or a completed one-time issue; inspect before retrying.

Tenants

Paths are relative to /v1/organizations/{organization_id}/tenants.

Method	Path	Operation
GET	base path	List organization tenants.
POST	base path	Create a tenant.
GET	/{tenant_id}	Inspect lifecycle and attachment state.
POST	/{tenant_id}:retry	Retry provisioning.
POST	/{tenant_id}:offboard	Withdraw access and start irreversible cleanup.

Create with an Idempotency-Key and JSON body:

{"display_name": "bluewater-bank", "mode": "saas"}

The deployment controls supported modes and quotas. Creation returns 202 while provisioning runs. A tenant becomes usable only when status is active and attachment state is ready. Organization machine clients gain reach automatically at that point.

Offboard with {"confirm": "<exact-tenant-id>"}. It returns 202, withdraws machine reach immediately, and cleans up asynchronously. Preserve required data before confirming.

For runtime calls made by a machine client, see Authenticate a backend and the application API reference.