---
title: "How to create and delete workspaces"
description: "Create, list, and delete workspaces, and read the quota you are working against."
---

> Documentation Index
> Fetch the complete documentation index at: https://tee.hypetrade.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash
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

```bash
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`.

> **The password is not recoverable**
>
> The workspace password is the only thing that opens the workspace. TEE Docker
> cannot reset it and cannot recover its contents without it. Store it the way you
> would store a root credential.

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

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

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

## Delete

```bash
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:

```bash
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.

> **force revokes live tokens**
>
> `force=true` deletes the workspace and invalidates the sessions using it. Use it
> only when revoking those tokens is what you actually intend.

Deleting a workspace destroys its accounts and their key material. If anything
inside needs to survive, [export it](/guides/export-key-material/) first.

## Failures worth handling

| Code | Status | What happened |
|---|---|---|
| `invalid_slug` | 400 | Slug syntax is wrong |
| `workspace_exists` | 409 | Slug already in use |
| `workspace_not_found` | 404 | No such workspace for this tenant |
| `workspace_in_use` | 409 | Open session; retry with `force=true` if intended |
| `quota_workspaces_exceeded` | 409 | Tenant workspace limit reached |
| `workspace_creation_rate_limited` | 429 | Creating too quickly |
| `workspace_recreation_cooldown` | 429 | Slug was recently deleted |

## Related

- [Workspaces endpoints](/api/workspaces/) — exact shapes
- [Authenticate](/guides/authenticate/) — opening one you created

Source: https://tee.hypetrade.xyz/guides/manage-workspaces/index.mdx