Skip to content
Authrim

Clone tenant settings into a new tenant.

POST
/api/admin/tenants/{id}/clone
Code sample: Shell / cURL 
curl --request POST \
  --url https://auth.example.com/api/admin/tenants/example/clone \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "id": "acme-copy", "name": "Acme Copy", "description": "Cloned tenant for staging.", "copy": { "settings": true, "clients": true, "client_credentials": false, "roles": true, "admin_access": false, "webhooks": false } }'

Provision a new isolated tenant through the normal tenant creation path, then copy the selected tenant settings, roles, Admin access assignments, clients, and webhooks. Tenant signing private keys are never copied; the destination receives a newly generated key. The source tenant must be active. Stored secret settings and credential hashes are copied only when explicitly requested. End-user accounts and their role assignments are never copied. This operation is platform-admin scoped and does not use X-Tenant-Id to identify the destination. The endpoint returns 202 and the durable Control Plane provisioning operation performs clone preparation before Lookup activation. The destination remains non-routable and in provisioning state until all selected resources, clone-preparation audit evidence, and a fresh signing-key rotation succeed. A success audit event is written after activation. The required Idempotency-Key is retained for 15 minutes. Synchronous work is limited to an estimated 40 database queries and 10 KV records, with a 256 KiB limit per selected KV value; callers can reduce selected categories when a limit is exceeded. Machine callers additionally require admin:tenants:lifecycle:standard; a global tenant scope alone is not sufficient. The response warns callers that copied KV-backed configuration is eventually consistent across regions and should be allowed to propagate before production traffic is directed to the destination.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required
string

Header Parameters

Section titled “Header Parameters ”
Idempotency-Key
required
string
>= 1 characters <= 255 characters

Required replay-protection key retained for 15 minutes.

Request Body required

Section titled “Request Body required ”
Media type application/json
object
id
required
string
>= 1 characters <= 63 characters /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/
tenant_code
string
>= 1 characters <= 63 characters /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/
name
required
string
>= 1 characters <= 200 characters
description
string
<= 500 characters
copy
object
settings

Copy tenant-scoped settings and policy. Destination-bound tenant identity values, including the tenant ID, name, base domain, allowed domains, allowed identifiers, allowed origins, runtime storage/audit/residency profiles, redirect-trust origins, and signing-key selections, are reset or preserved from destination defaults. References to users, groups, and clients that are not selected for copying are removed. Unclassified settings are omitted.

boolean
default: true
secret_settings

Copy explicitly classified confidential settings, including credential, external IdP, federation, plugin, backup, and directory connector relay configuration. Requires settings and should only be used within the same trust boundary.

boolean
clients

Copy OAuth/OIDC clients, Web Origin registry entries, client-scoped settings, Client Contracts, and OIDC client trust policies. Consent overrides and Flow assignments are reported as skipped because their referenced tenant resources are not part of this option.

boolean
client_credentials

Copy client secret hashes and credential tokens. Requires clients.

boolean
roles

Copy custom application roles and automatic role-assignment rules. End-user role assignments are excluded because end-user accounts are not copied.

boolean
default: true
admin_access

Copy custom Admin roles and active tenant-scoped Admin-user role assignments. Assignments whose scope does not exactly match the source tenant are excluded.

boolean
webhooks
boolean
webhook_secrets

Copy encrypted webhook signing secrets and headers. Requires webhooks.

boolean
key
additional properties
include_clients

Legacy alias for copy.clients.

boolean
include_roles

Legacy alias for copy.roles.

boolean
default: true
include_webhooks

Legacy alias for copy.webhooks.

boolean
key
additional properties
Example 
{
  "id": "acme-copy",
  "name": "Acme Copy",
  "description": "Cloned tenant for staging.",
  "copy": {
    "settings": true,
    "clients": true,
    "client_credentials": false,
    "roles": true,
    "admin_access": false,
    "webhooks": false
  }
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Tenant clone response.

Media type application/json
object
id
required
string
tenant_code
required
string
name
required
string
description
required
string | null
isolation_policy
required

Physical placement scope. Both modes expand automatically.

string
Allowed values: shared_pool tenant_exclusive
lifecycle_state
required
string
Allowed values: provisioning active suspended frozen migration_read_only deleting deleted restore_pending restore_validating
is_default
required
boolean
created_at
required

Unix timestamp in seconds.

integer format: int64
updated_at
required

Unix timestamp in seconds.

integer format: int64
provisioning

Present when tenant creation is accepted for asynchronous Control provisioning.

object
mode
string
Allowed values: control-plane
operation_id
required
string
tenant_id
required
string
operation_kind
required
string
Allowed values: create clone
source_tenant_id
required
string | null
isolation_policy
required
string
Allowed values: shared_pool tenant_exclusive
status
required
string
Allowed values: queued running waiting_retry blocked succeeded canceled
current_step
required
string
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
created_at
required
integer format: int64
updated_at
required
integer format: int64
completed_at
required
integer | null format: int64
preparation_result
required
object | null
capacity_operation_ids
required
object
key
additional properties
string
capacity_operations
Array<object>
object
data_role
required
string
Allowed values: tenant_core/default tenant_core/users tenant_pii
operation_id
required
string
status
required
string
Allowed values: queued running waiting_retry blocked succeeded canceled
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
updated_at
required
integer format: int64
steps
required
Array<object>
object
step_key
required
string
Allowed values: request_accepted capacity_check reserve_default_route tenant_seed registry_publish tenant_smoke tenant_prepare lookup_activate tenant_active
status
required
string
Allowed values: queued running waiting_retry blocked succeeded skipped canceled rolled_back
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
observed_resource_id
required
string | null
progress_current
integer | null
progress_total
integer | null
started_at
required
integer | null format: int64
completed_at
required
integer | null format: int64
updated_at
required
integer format: int64
key
additional properties
key
additional properties
steps
required
Array<object>
object
step_key
required
string
Allowed values: request_accepted capacity_check reserve_default_route tenant_seed registry_publish tenant_smoke tenant_prepare lookup_activate tenant_active
status
required
string
Allowed values: queued running waiting_retry blocked succeeded skipped canceled rolled_back
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
observed_resource_id
required
string | null
progress_current
integer | null
progress_total
integer | null
started_at
required
integer | null format: int64
completed_at
required
integer | null format: int64
updated_at
required
integer format: int64
key
additional properties
key
additional properties
source_tenant_id
required
string
source_tenant_name
required
string
copy
required
object
key
additional properties
boolean
cloned_items
required
object
settings
required
integer
secret_settings_skipped
required
integer
unclassified_settings_skipped
required
integer
clients
required
integer
client_settings
required
integer
client_contracts
required
integer
client_web_origins
required
integer
client_trust_policies
required
integer
client_consent_overrides_skipped
required
integer
client_flow_assignments_skipped
required
integer
roles
required
integer
role_assignment_rules
required
integer
role_references_unresolved
required
integer
role_assignment_rules_skipped
required
integer
admin_roles
required
integer
admin_role_assignments
required
integer
admin_role_assignments_skipped
required
integer
admin_role_inheritance_unresolved
required
integer
webhooks
required
integer
client_webhooks_skipped
required
integer
key
additional properties
signing_keys
required
object
copied
required
boolean
generated
required
boolean
key
additional properties
warnings
required
Array<string>
Example 
{
  "id": "acme",
  "tenant_code": "acme",
  "name": "Acme Corp",
  "description": "Production tenant for Acme Corp.",
  "isolation_policy": "tenant_exclusive",
  "lifecycle_state": "active",
  "is_default": false,
  "created_at": 1770000000,
  "updated_at": 1770000000,
  "signing_keys": {
    "copied": false,
    "generated": true
  }
}

202

Section titled “202 ”

Accepted asynchronous Control Plane tenant clone operation.

Media type application/json
object
id
required
string
tenant_code
required
string
name
required
string
description
required
string | null
isolation_policy
required

Physical placement scope. Both modes expand automatically.

string
Allowed values: shared_pool tenant_exclusive
lifecycle_state
required
string
Allowed values: provisioning active suspended frozen migration_read_only deleting deleted restore_pending restore_validating
is_default
required
boolean
created_at
required

Unix timestamp in seconds.

integer format: int64
updated_at
required

Unix timestamp in seconds.

integer format: int64
provisioning
required

Present when tenant creation is accepted for asynchronous Control provisioning.

object
mode
string
Allowed values: control-plane
operation_id
required
string
tenant_id
required
string
operation_kind
required
string
Allowed values: create clone
source_tenant_id
required
string | null
isolation_policy
required
string
Allowed values: shared_pool tenant_exclusive
status
required
string
Allowed values: queued running waiting_retry blocked succeeded canceled
current_step
required
string
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
created_at
required
integer format: int64
updated_at
required
integer format: int64
completed_at
required
integer | null format: int64
preparation_result
required
object | null
capacity_operation_ids
required
object
key
additional properties
string
capacity_operations
Array<object>
object
data_role
required
string
Allowed values: tenant_core/default tenant_core/users tenant_pii
operation_id
required
string
status
required
string
Allowed values: queued running waiting_retry blocked succeeded canceled
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
updated_at
required
integer format: int64
steps
required
Array<object>
object
step_key
required
string
Allowed values: request_accepted capacity_check reserve_default_route tenant_seed registry_publish tenant_smoke tenant_prepare lookup_activate tenant_active
status
required
string
Allowed values: queued running waiting_retry blocked succeeded skipped canceled rolled_back
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
observed_resource_id
required
string | null
progress_current
integer | null
progress_total
integer | null
started_at
required
integer | null format: int64
completed_at
required
integer | null format: int64
updated_at
required
integer format: int64
key
additional properties
key
additional properties
steps
required
Array<object>
object
step_key
required
string
Allowed values: request_accepted capacity_check reserve_default_route tenant_seed registry_publish tenant_smoke tenant_prepare lookup_activate tenant_active
status
required
string
Allowed values: queued running waiting_retry blocked succeeded skipped canceled rolled_back
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
observed_resource_id
required
string | null
progress_current
integer | null
progress_total
integer | null
started_at
required
integer | null format: int64
completed_at
required
integer | null format: int64
updated_at
required
integer format: int64
key
additional properties
key
additional properties
source_tenant_id
required
string
source_tenant_name
required
string
copy
required
object
key
additional properties
boolean
provisioning
required
object
mode
required
string
Allowed values: control-plane
operation_id
required
string
tenant_id
required
string
operation_kind
required
string
Allowed values: create clone
source_tenant_id
required
string | null
isolation_policy
required
string
Allowed values: shared_pool tenant_exclusive
status
required
string
Allowed values: queued running waiting_retry blocked succeeded canceled
current_step
required
string
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
created_at
required
integer format: int64
updated_at
required
integer format: int64
completed_at
required
integer | null format: int64
preparation_result
required
object | null
capacity_operation_ids
required
object
key
additional properties
string
capacity_operations
Array<object>
object
data_role
required
string
Allowed values: tenant_core/default tenant_core/users tenant_pii
operation_id
required
string
status
required
string
Allowed values: queued running waiting_retry blocked succeeded canceled
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
updated_at
required
integer format: int64
steps
required
Array<object>
object
step_key
required
string
Allowed values: request_accepted capacity_check reserve_default_route tenant_seed registry_publish tenant_smoke tenant_prepare lookup_activate tenant_active
status
required
string
Allowed values: queued running waiting_retry blocked succeeded skipped canceled rolled_back
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
observed_resource_id
required
string | null
progress_current
integer | null
progress_total
integer | null
started_at
required
integer | null format: int64
completed_at
required
integer | null format: int64
updated_at
required
integer format: int64
key
additional properties
key
additional properties
steps
required
Array<object>
object
step_key
required
string
Allowed values: request_accepted capacity_check reserve_default_route tenant_seed registry_publish tenant_smoke tenant_prepare lookup_activate tenant_active
status
required
string
Allowed values: queued running waiting_retry blocked succeeded skipped canceled rolled_back
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
observed_resource_id
required
string | null
progress_current
integer | null
progress_total
integer | null
started_at
required
integer | null format: int64
completed_at
required
integer | null format: int64
updated_at
required
integer format: int64
key
additional properties
Example 
{
  "id": "acme",
  "tenant_code": "acme",
  "name": "Acme Corp",
  "description": "Production tenant for Acme Corp.",
  "isolation_policy": "tenant_exclusive",
  "lifecycle_state": "active",
  "is_default": false,
  "created_at": 1770000000,
  "updated_at": 1770000000,
  "provisioning": {
    "mode": "control-plane",
    "operation_kind": "create",
    "isolation_policy": "shared_pool",
    "status": "queued",
    "capacity_operations": [
      {
        "data_role": "tenant_core/default",
        "status": "queued",
        "steps": [
          {
            "step_key": "request_accepted",
            "status": "queued"
          }
        ]
      }
    ],
    "steps": [
      {
        "step_key": "request_accepted",
        "status": "queued"
      }
    ]
  }
}

400

Section titled “400 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

403

Section titled “403 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

404

Section titled “404 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

409

Section titled “409 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

425

Section titled “425 ”

A request using the same Idempotency-Key is still in progress.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

Headers

Section titled “Headers ”
Retry-After
integer

Suggested retry delay in seconds.

429

Section titled “429 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

500

Section titled “500 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

503

Section titled “503 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}