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

# Create an API key

`POST /api/v1/account/keys`

## Request

- Base URL: `https://api.dotsy.ai`
- URL: `https://api.dotsy.ai/api/v1/account/keys`
- Auth: HTTP bearer

Creates a `pga_…` key for the active workspace and returns it, secret included. The secret stays readable through `listApiKeys`. Every field is optional: the default is a `write` key for all sites.

## Headers

- `X-Dotsy-Workspace` string

## Request body

- CreateApiKeyRequest
  - `label` string: A name for the key, up to 100 characters.
  - `scope` 'read' | 'write' | 'admin': `read`, `write` (default) or `admin`. `read` can only GET; `admin` can also manage keys.
  - `siteSlugs` string[]: Limit the key to these sites. Leave it out or send `[]` for all sites. Each slug must be a site in this workspace, or the request answers 400 `site_not_found`.

## Response `201`

The new key.

- ApiKey
  - `id` string, required
  - `label` string, nullable, required
  - `scope` 'read' | 'write' | 'admin', required
  - `siteSlugs` string[], nullable, required: The sites the key is limited to, or null for all sites.
  - `createdAt` number, required: Creation time, Unix ms.
  - `secret` string, nullable, required: The key itself (`pga_…`). Null for an old key whose secret was never stored.

## Other responses

- `400`: `invalid_body`, or `site_not_found`: a slug in `siteSlugs` is not a site in this workspace.
- `401`: Missing or invalid credentials.
- `403`: `admin_required`: the key's scope is not `admin`. `workspace_admin_required`: you are a workspace Member, and only an Owner or Admin can manage keys. `guest_only`: this account can't create keys. `guest_requires_account`: a guest token can't manage keys.
- `500`: `auth_secret_missing`: the server has no signing secret configured, so keys can't be created.

---

[API](https://skmtc.dev/dotsy/apis/dotsy-api.md) · [All operations](https://skmtc.dev/dotsy/apis/dotsy-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dotsy/apis/dotsy-api/revisions/4272ed3b85d7?raw)