---
title: "Create API key"
method: POST
path: "/v1/api-keys"
tags: ["API Keys"]
---

# Create API key

`POST /v1/api-keys`

## Request

- Base URL: `https://api.deadsimple.email`
- URL: `https://api.deadsimple.email/v1/api-keys`
- Auth: HTTP bearer

## Headers

- `X-Workspace-Id` string, uuid

## Request body

- object
  - `name` string, required
  - `permissions` string[]: Legacy scopes (read, write, admin) or granular permissions (resource.operation). Legacy scopes expand automatically — "read" grants all *.read permissions, "write" grants read + create/update/delete/send, "admin" grants everything. Granular examples: inboxes.read, messages.send, webhooks.create.
  - `workspace_id` string, uuid: Optional workspace ID to create a workspace-scoped API key
  - `inbox_ids` string[]: Optional inbox scope. The key can then only see and act on these inboxes: any other inbox of the account answers 404, account-wide listings (GET /v1/inboxes, /v1/messages, /v1/threads, /v1/metrics) are filtered to them, and the key cannot create inboxes. Every id must belong to the account (and to workspace_id when both are given). An inbox-scoped key may only mint keys scoped to a subset of its own inboxes. Keys without inbox_ids behave as before.

## Response `201`

API key created (key shown once). Includes `inbox_ids` (empty when unscoped).

---

[API](https://skmtc.dev/deadsimple/apis/dead-simple-email-api.md) · [All operations](https://skmtc.dev/deadsimple/apis/dead-simple-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/deadsimple/apis/dead-simple-email-api/revisions/c697881be131?raw)