Skip to main content
POST
Re-mint a Client Workspace Key
Creating a 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.
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)

Body

Minting

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

What a client already has

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

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.