---
title: "Create a workspace and its first API key"
method: POST
path: "/v1/workspaces"
tags: ["Workspace"]
---

# Create a workspace and its first API key

`POST /v1/workspaces`

## Request

- Base URL: `https://ratchetgate.com`
- URL: `https://ratchetgate.com/v1/workspaces`
- Auth: HTTP bearer

Self-serve signup. Returns the API key exactly once — it is stored only as a keyed hash and cannot be retrieved again. Also returns a console session cookie.

## Request body

- object
  - `name` string, required
  - `email` string, email, required

## Response `201`

Default Response

- object
  - `workspace_id` string
  - `name` string
  - `api_key` string: OPERATOR key: full scope, for the console and for changing policy. Shown once. Store it securely and do not give it to an agent.
  - `api_key_prefix` string
  - `agent_api_key` string: AGENT key: effects:begin and effects:report only. This is the one to put in your code. It cannot change policy, mint keys, or close a circuit breaker — so an agent holding it cannot switch off its own containment.
  - `agent_api_key_prefix` string
  - `plan` string
  - `console_url` string
  - `next_step` object: A runnable command using the key just issued, what to expect back, and the follow-up call that new integrations forget.

## Other responses

- `400`: Invalid request.
- `401`: Missing or invalid API key.
- `402`: Insufficient prepaid credit.
- `403`: Scope, policy, or budget refusal.
- `404`: Not found.
- `409`: Conflicting state or idempotency-key reuse.
- `413`: Payload too large.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/ratchetgate/apis/ratchet-api.md) · [All operations](https://skmtc.dev/ratchetgate/apis/ratchet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ratchetgate/apis/ratchet-api/revisions/5712f33c692f?raw)