Provisioning API · Internal testing only
deprovisionPersonas
const url = 'https://api.builders.ac/api/provisioning/v1alpha1/personas/deprovision';const options = { method: 'POST', headers: { 'Idempotency-Key': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"persona_ids":["per_01k5n7qd2vb8ye4ka3mzt9rf6x"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.builders.ac/api/provisioning/v1alpha1/personas/deprovision \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example' \ --data '{ "persona_ids": [ "per_01k5n7qd2vb8ye4ka3mzt9rf6x" ] }'Deletes one to 100 Personas from one Workspace under a single proof. A Persona an inbox row still references is kept rather than failing the batch, and the response lists what was deleted and what was refused. Proof is obtained on demand: first send this exact request without Sealed-Proof, open the Sealed-Nonce from the 403 response, then retry without changing the request.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”A client-generated key containing 1–255 printable ASCII characters (0x20 through 0x7E). Reuse it only for exact retries of one logical request.
The one-time plaintext obtained by opening the Sealed-Nonce challenge for this exact request. Omit it initially; after a 403 challenge, retry with the same method, route, resources, query, body, credential, and Idempotency-Key.
Request Bodyrequired
Section titled “Request Bodyrequired”object
One to 100 distinct Personas from the same Workspace. Order and casing do not change the identity of the request, so a retry may reorder or re-case the list.
Responses
Section titled “Responses”Batch processed. Every target is reported as deleted or refused; a partial outcome is normal and is not an error.
object
The Personas this request deleted, ascending by id. A Persona already deleted by an earlier request is never in this list, because it is no longer addressable.
The Personas this request kept, ascending by id, each with the reason. Empty when every target was deleted.
object
Canonical lowercase TypeID.
Why this one target was kept, as a problem code. The same extensible vocabulary as a Problem body; see GET /problems. Create a new persona for future inboxes. A persona already in use cannot be updated or deleted.
Example
{ "object": "persona_deprovision_result", "deleted": [ "per_01k5n7qd2vb8ye4ka3mzt9rf6x" ], "refused": [ { "persona_id": "per_01k5n7qd2vb8ye4ka3mzt9rf6x", "code": "persona_in_use" } ]}Headers
Section titled “Headers”Present with value true only for a stored exact replay.
The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Idempotency key required. The example shows idempotency_key_required.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/idempotency_key_required", "title": "Idempotency key required", "status": 400, "detail": "This request requires a valid Idempotency-Key header.", "code": "idempotency_key_required", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Authentication required. The example shows authentication_required; this status is also answered with invalid_api_key. Branch on code, not on the status.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/authentication_required", "title": "Authentication required", "status": 401, "detail": "Provide an active Provisioning API Key as a Bearer token.", "code": "authentication_required", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Either the Account lacks permission, or API-secret proof is missing or invalid. A proof challenge includes Sealed-Nonce and WWW-Authenticate.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Examples
API Secret proof required
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/insufficient_proof", "title": "API Secret proof required", "status": 403, "detail": "Open the Sealed-Nonce with the API Secret, then retry this request with the resulting value in Sealed-Proof.", "code": "insufficient_proof", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Account inactive
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/account_inactive", "title": "Account inactive", "status": 403, "detail": "This account is inactive.", "code": "account_inactive", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”A credential- and request-bound, single-use age v1 challenge. Strip age-v1., Base64URL-decode the remaining text to the binary age file, then open it with the matching API Secret.
Present as Sealed error="insufficient_proof" only for a proof challenge.
Proof challenges are never cached.
The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Not found. The example shows not_found.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/not_found", "title": "Not found", "status": 404, "detail": "The requested resource was not found.", "code": "not_found", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Request already in progress. The example shows idempotency_in_progress; this status is also answered with external_id_conflict, persona_in_use, workspace_archived, domain_not_ready, inbox_address_unavailable, operation_cancelled, resource_operation_in_progress, workspace_limit_reached, workspace_not_empty, workspace_is_default, workspace_last_active, nameservers_not_delegated, external_id_immutable, domain_already_exists, domain_unavailable, resource_quota_exceeded, domain_inbox_capacity_exceeded, domain_inbox_count_invalid, domain_not_active, domain_traffic_unavailable, redirect_not_configured, domain_not_reconnectable, account_not_provisioned, provider_account_in_use, no_inboxes_to_upload. Branch on code, not on the status.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/idempotency_in_progress", "title": "Request already in progress", "status": 409, "detail": "A request using this idempotency key is still in progress.", "code": "idempotency_in_progress", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Validation failed. The example shows validation_error; this status is also answered with idempotency_mismatch, invalid_sealed_value, mailbox_upload_unavailable, provider_credentials_invalid, domains_not_bound, sequencer_targets_mixed. Branch on code, not on the status.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/validation_error", "title": "Validation failed", "status": 422, "detail": "One or more request fields are invalid.", "code": "validation_error", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3", "errors": { "display_name": [ "The display name must not be blank." ] }}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Rate limit exceeded. The example shows rate_limit_exceeded.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/rate_limit_exceeded", "title": "Rate limit exceeded", "status": 429, "detail": "Too many requests were made for this policy.", "code": "rate_limit_exceeded", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3", "retry_after": "2026-04-15T09:16:04Z"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Service unavailable. The example shows service_unavailable; this status is also answered with encryption_keys_unavailable, provider_unreachable. Branch on code, not on the status.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/service_unavailable", "title": "Service unavailable", "status": 503, "detail": "Retry the request later; the service is temporarily unavailable.", "code": "service_unavailable", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.