---
title: "Creates an API key for the authenticated account and returns the full key in the response body."
method: POST
path: "/api/keys"
tags: ["api-keys"]
---

# Creates an API key for the authenticated account and returns the full key in the response body.

`POST /api/keys`

## Request

- Base URL: `https://api.pricklymails.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pricklymails.com/api/keys`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

## Request body

- CreateApiKeyRequest: `POST /api/keys` request body.
  - `enabled_checks` string[], nullable: Verification checks to enable: `"syntax"`, `"mx"`, `"smtp"`, `"disposable"`, `"role"`, `"free"` or `"catchall"`.
  - `environment` string, nullable: Environment of the key: `"live"` or `"test"`. Defaults to `"live"` when absent.
  - `name` string, required: Display name shown in the dashboard.
  - `scopes` string[], nullable: Scopes to grant, for example `"email:verify:single"`.

## Response `201`

Key created; `raw_key` is shown once.

- ApiKeyCreatedResponse
  - `key` ApiKeyResponse, required: Metadata of an API key, returned when listing, reading, updating or revoking keys.
    - `created_at` string, required: RFC 3339 creation timestamp.
    - `enabled_checks` string[], required: Verification checks enabled for the key.
    - `environment` string, required: Environment of the key: `"live"` or `"test"`.
    - `expires_at` string, nullable: RFC 3339 expiry timestamp, or `null` when the key does not expire.
    - `is_active` boolean, required: Whether the key can currently authenticate (not revoked and not expired).
    - `last_used_at` string, nullable: RFC 3339 timestamp of the last request made with the key, or `null` when it was never used.
    - `name` string, required: Display name of the key.
    - `prefix` string, required: Visible prefix of the key (for example `pm_live_abc12345`).
    - `rate_limit` RateLimitDto, required: Request budget of an API key.
      - `per_minute` integer, required: Maximum number of requests the key may make per minute.
    - `request_count` integer, required: Total number of requests made with the key.
    - `revoked_at` string, nullable: RFC 3339 timestamp of the revocation, or `null` when the key is not revoked.
    - `scopes` string[], required: Scopes granted to the key.
    - `uuid` string, required: Public UUID of the key.
  - `raw_key` string, required: The full API key. It is returned only once, so store it securely.

## Other responses

- `400`: Invalid name, environment, scopes, or checks.
- `401`: Missing or invalid API key, session token, or agent token.
- `403`: Plan key limit reached, a check is not allowed for the plan, or the key or agent token lacks the `api_keys:create` scope.

---

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