How to create and delete workspaces

Workspaces are administered entirely with tenant credentials. None of these routes take a workspace token.

Check your quota first

curl "$API_URL/quota" \
  -H "X-Api-Key: $API_KEY" -H "X-Api-Secret: $API_SECRET"

This reports two of the limits your operator set — how many workspaces you may hold, and how many wallets in total — with your current usage of each. Reading it before a bulk provisioning run is cheaper than discovering the ceiling halfway through.

It does not report how many workspaces may be held open at once. That is a separate ceiling, enforced by session_capacity_exceeded at mint time, and no route exposes it.

Create

curl -X POST "$API_URL/workspaces" \
  -H "X-Api-Key: $API_KEY" -H "X-Api-Secret: $API_SECRET" \
  -H "content-type: application/json" \
  -d '{"slug":"demo","password":"a-strong-workspace-password"}'

Slugs are lowercase letters, digits, and hyphens, starting alphanumeric, up to 63 characters. A malformed slug returns 400 with invalid_slug; a slug already in use returns 409 with workspace_exists.

Creation is rate-limited per tenant (429, workspace_creation_rate_limited), and a workspace that was recently deleted cannot immediately be recreated under the same slug (429, workspace_recreation_cooldown).

List

curl "$API_URL/workspaces" \
  -H "X-Api-Key: $API_KEY" -H "X-Api-Secret: $API_SECRET"

{
  "workspaces": [
    { "slug": "demo", "createdAt": "2025-06-01T09:15:00.000Z", "walletCount": 12 }
  ]
}

Delete

curl -X DELETE "$API_URL/workspaces/demo" \
  -H "X-Api-Key: $API_KEY" -H "X-Api-Secret: $API_SECRET"

Returns 204. If the workspace currently has an open session, the call is refused with 409 and workspace_in_use rather than pulling the floor out from under an active caller.

To delete anyway, opt in explicitly:

curl -X DELETE "$API_URL/workspaces/demo?force=true" \
  -H "X-Api-Key: $API_KEY" -H "X-Api-Secret: $API_SECRET"

force accepts exactly true or false. Any other value returns 400 with invalid_parameter — there is no truthy-string coercion.

Deleting a workspace destroys its accounts and their key material. If anything inside needs to survive, export it first.

Failures worth handling

Related

• Workspaces endpoints — exact shapes
• Authenticate — opening one you created