> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Re-mint a Client Workspace Key

> Mint a fresh workspace API key for any client in your agency — for a workspace created before keys were returned, or one whose key was lost or leaked.

<Note>
  [Creating a workspace](/api-reference/endpoint/agency-create-workspace) already
  returns its key in the same response, which covers onboarding. This endpoint
  covers the two cases that happen afterwards: a client created before that
  existed, and a key that was lost or leaked.
</Note>

Without it, both meant signing in as the client and copying a key out of their
dashboard by hand — the last manual step in an otherwise scripted onboarding.

## Endpoint

* **Method**: `POST` to mint, `GET` to list what a client already has
* **Path**: `/api/agency/workspace-keys`
* **Auth**: `Authorization: Bearer tucoagency_xxxxxxxxxxxxx` ([agency key](/api-reference/agency-api-keys))

## Body

| Field | Type | Required | Notes |
| - | - | - | - |
| `workspaceId` | string | **yes** | A client `clerkOrgId`. Must be in your agency |
| `name` | string | no | Shown in that client's dashboard. Defaults to `Re-minted by agency`. Truncated at 120 characters |
| `revokeExisting` | boolean | no | Default `false`. See below — this is the field that matters |

## Minting

```bash theme={null}
curl https://app.tuco.ai/api/agency/workspace-keys \
  -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT",
    "name": "Acme Roofing — backend"
  }'
```

```json theme={null}
{
  "id": "6ac52ed996359b3643c71939",
  "workspaceId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT",
  "key": "tuco_xCsfhTiXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "Acme Roofing — backend",
  "revokedExisting": 0,
  "warning": "Save this key now. You will not be able to see it again."
}
```

`201 Created`. The key is shown **once** — Tuco stores only its hash.

It is a normal workspace key: it works on every documented endpoint for that
one workspace, and on no other. It is not an agency key and cannot reach any
agency endpoint.

## Additive by default

Minting does **not** revoke what is already there.

The common case is "we lost our copy", and silently killing a live integration
to solve that is worse than the problem. So a new key is added alongside the
existing ones and nothing breaks.

```bash theme={null}
  -d '{ "workspaceId": "org_…", "revokeExisting": true }'
```

Pass `revokeExisting: true` for the leaked-key case, where killing it is the
point. Every active key on that workspace is deactivated **before** the new one
is created, so there is no window in which the leaked key and its replacement
are both live. The count comes back as `revokedExisting`.

<Warning>
  `revokeExisting: true` breaks any integration still using an old key — the
  client's own dashboard key included. Use it when a key has leaked, not as
  routine hygiene.
</Warning>

## What a client already has

```bash theme={null}
curl "https://app.tuco.ai/api/agency/workspace-keys?workspaceId=org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT" \
  -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx"
```

```json theme={null}
{
  "agencyId": "user_3H08IRicrVUYLDZRyOh4jKRVwrx",
  "workspaceId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT",
  "apiKeys": [
    {
      "id": "6ac52ed996359b3643c71939",
      "name": "Acme Roofing — backend",
      "isActive": true,
      "lastUsedAt": "2026-10-06T19:04:11.882Z",
      "createdAt": "2026-10-06T18:55:02.117Z"
    }
  ]
}
```

Secrets are never returned here — only at creation. `lastUsedAt` is the useful
read before revoking: a key that has never been used (`null`) is safe to kill.

Agency keys are deliberately excluded from this list. It reports workspace keys
only.

## Error responses

| Status | Code | When |
| - | - | - |
| `400` | `WORKSPACE_REQUIRED` | `workspaceId` missing. There is no default |
| `401` | `UNAUTHORIZED` | Missing, unknown, revoked or expired key |
| `403` | `AGENCY_KEY_REQUIRED` | A workspace key (`tuco_…`) was used |
| `403` | `NOT_YOUR_WORKSPACE` | That workspace is not part of your agency |

Scoped by the same ownership check as every other agency endpoint, so a key can
only ever mint into a workspace in its own group.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.