Provisioning API · Internal testing only
deleteWorkspace
const url = 'https://api.builders.ac/api/provisioning/v1alpha1/workspaces/wsp_01k5n2rf8bd3xa9e7m4jt6vq5h';const options = {method: 'DELETE', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request DELETE \ --url https://api.builders.ac/api/provisioning/v1alpha1/workspaces/wsp_01k5n2rf8bd3xa9e7m4jt6vq5h \ --header 'Authorization: Bearer <token>'Empty workspaces only. A workspace with resources returns workspace_not_empty; the default workspace returns workspace_is_default. A proof is consumed before these guards, so a refusal also spends it. This DELETE takes no Idempotency-Key. 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”Path Parameters
Section titled “Path Parameters”Workspace TypeIDs are accepted case-insensitively. Responses use canonical lowercase.
Header Parameters
Section titled “Header Parameters”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.
Responses
Section titled “Responses”Workspace deleted; its external_id is released
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 permission is absent, or API-secret proof is missing or invalid. A proof challenge carries a request-bound Sealed-Nonce and WWW-Authenticate; open it and retry this exact request.
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/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"}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.
Proof challenges are never cached.
Present as Sealed error="insufficient_proof" only for a proof challenge.
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.
The workspace still holds resources — counts lists them — or it is the account’s permanent default workspace.
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
Live rows per resource behind this workspace. Deleting it needs every count at zero.
object
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
Workspace not empty
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/workspace_not_empty", "title": "Workspace not empty", "status": 409, "detail": "The workspace still holds resources and cannot be deleted. Deprovision them first; `counts` lists what is in the way.", "code": "workspace_not_empty", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3", "counts": { "senders": 3, "domains": 3, "mailboxes": 3, "personas": 3 }}Workspace cannot be deleted
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/workspace_is_default", "title": "Workspace cannot be deleted", "status": 409, "detail": "This is the account's default workspace, which is permanent. Delete a different workspace or leave this one in place.", "code": "workspace_is_default", "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.
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.