---
title: "Read a workspace, lock and unlock accounts"
description: "The current workspace — info, account listing, assets, and account lock and unlock."
---

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

# Read a workspace, lock and unlock accounts

These routes address the workspace named by the token's own claim — no
workspace-token route takes the workspace in its path, so a path and a token
can never disagree about which one is in play. (The tenant-tier route
`DELETE /v1/workspaces/{slug}` does name a workspace in its path; it carries no
token to disagree with.)

**Auth: workspace token** on every route.

## `GET /v1/workspace`

Current workspace state. Scope: `read`. Returns `200`.

```json
{
  "workspace": "demo",
  "locked": false,
  "accounts": 3,
  "damagedAccounts": 0,
  "expiresAt": "2026-08-18T12:34:56.000Z"
}
```

| Field | Meaning |
|---|---|
| `accounts` | Number of accounts in the workspace |
| `damagedAccounts` | Count of accounts whose records could not be read |
| `expiresAt` | When the idle clock currently runs out |

> **damagedAccounts is a signal, not noise**
>
> It is surfaced as a count rather than a silently shortened account list,
> because a short list is exactly how missing records go unnoticed. A non-zero
> value means some records are unreadable — tell your operator.

## `GET /v1/accounts`

List every account in the workspace. Scope: `read`. Returns `200`.

```json
{
  "accounts": [
{
  "slug": "treasury-a1b2",
  "displayName": "Treasury",
  "kind": "HD",
  "hasOwnPassword": false,
  "locked": false,
  "wallets": 4
}
  ]
}
```

## `GET /v1/accounts/{slug}`

Resolve one account, unlocking it lazily if it shares the workspace password.
Scope: `read`. Returns `200`.

```json
{
  "account": {
"slug": "treasury-a1b2",
"displayName": "Treasury",
"kind": "HD",
"hasOwnPassword": false,
"locked": false,
"wallets": 4
  }
}
```

An account with its own password returns `423` with `account_locked` until
explicitly unlocked.

## `GET /v1/workspace/assets`

Assets on one network. Scope: `read`. Returns `200`.

### Query parameters

| Parameter | Required | Notes |
|---|---|---|
| `network` | yes | Network slug |

The network must be named — listing every network's assets would be an
unbounded response shaped by how many networks the tenant has registered.

```json
{
  "network": "ethereum",
  "assets": [
{
  "id": 1,
  "symbol": "ETH",
  "name": "Ether",
  "decimals": 18,
  "native": true,
  "contractAddress": null
}
  ]
}
```

## `POST /v1/accounts/{slug}/unlock`

Reopen an account that is locked. **Any scope.** Returns `204`.

```json
{ "accountPassword": "…" }
```

An account created with `hasOwnPassword: true` needs this before its first
use, with its own password.

Every other account needs it too, eventually. An account sharing the workspace
password opens transparently the first time you touch it, but that opening is a
custody window bounded by `ttl.accountAbsoluteSec` — **five minutes by
default**. When it lapses the account locks, and every route touching it answers
`423` and `account_locked` until you call this one. Pass the workspace password
in `accountPassword`.

The same applies after `POST /v1/accounts/{slug}/lock`, which locks any account
regardless of how it was created.

Failed attempts are rate-limited — `429` with `account_unlock_rate_limited`.

## `POST /v1/accounts/{slug}/lock`

Lock an account again. **Any scope.** Returns `204`. No body.

> **Lock and unlock are scope-free**
>
> Both accept any workspace token regardless of scope. Unlocking is a
> precondition for work you are already authorised to do — the scope check still
> applies to whatever you do next.

## Errors

| Status | Code |
|---|---|
| 400 | `invalid_body`, `invalid_slug`, `invalid_parameter`, `unsupported_network` |
| 401 | `session_expired` |
| 403 | `scope_denied` |
| 404 | `account_not_found` |
| 423 | `account_locked` |
| 429 | `account_unlock_rate_limited` |

## Related

- [Manage accounts and wallets](/guides/manage-accounts-and-wallets/)
- [Accounts endpoints](/api/accounts/)

Source: https://tee.hypetrade.xyz/api/workspace/index.mdx