---
title: "Create a new API key"
method: POST
path: "/keys"
tags: ["API Key Management"]
---

# Create a new API key

`POST /keys`

## Request

- Base URL: `https://api.rateapi.dev`
- URL: `https://api.rateapi.dev/keys`
- Auth: none required

Creates a new API key for accessing the API. RateAPI—not the client—generates the credential. Supply a fresh, cryptographically random UUIDv4 in the optional `Idempotency-Key` header so a byte-identical retry can replay the same encrypted response for up to 24 hours without minting a second key. Callers that omit the header retain the legacy one-time response behavior and cannot recover a lost response. Store the returned credential securely; after the recovery window it cannot be retrieved.

New keys are created at **Tier 1 (Free)** with 20 requests per 30 days. **An email address is required** in the request body. Link your key to an organization for plan-level shared limits.

**Rate limit**: 1 key per IP address per 30 days to prevent abuse.

## Headers

- `Idempotency-Key` string, uuid

## Request body

- CreateKeyRequest: Required enrollment identity and optional bounded signup attribution.
  - `email` string, email, required: Required email address for account recovery and important API updates. Does not affect rate limits.
  - `source` string: Optional bounded signup-surface attribution, such as `npm-cli`.
  - `referrer` string: Optional bounded signup referrer attribution. Never used for authorization.

## Response `201`

API key created successfully

- CreateKeyResponse: A newly issued API-key registration. RateAPI generates `key`; its hash is stored long-term. When an enrollment UUID is supplied, the encrypted response is replayable for 24 hours and then queued for the next hourly deletion pass.
  - `id` string, required: Unique identifier for the API key. Use this ID for /keys/:id endpoints to check usage or disable the key.
  - `key` string, required: Server-generated API key to use in X-API-Key. A byte-identical retry with the same enrollment UUID can replay it for up to 24 hours; after that only the long-term hash remains.
  - `message` string, required: Warning message reminding you to store the key securely
  - `tier` TierInfo, required: The plan an API key is on, and the request quota that plan carries.
    - `level` 1 | 2 | 3, required: Tier level (1=Free, 2=Pro, 3=Enterprise)
    - `name` 'Free' | 'Pro' | 'Enterprise', required: Human-readable tier name
    - `limit` integer: Maximum requests allowed per window for this tier. Only present in CreateKeyResponse.
    - `windowDays` integer: Rate limit window in days. Only present in CreateKeyResponse.
  - `emailRegistered` boolean, required: Present and true when an email was provided and validated.

## Other responses

- `400`: Invalid Idempotency-Key UUIDv4, invalid or missing email, or malformed JSON.
- `422`: Idempotency-Key was reused with a different request body.
- `429`: Rate limit exceeded for key creation
- `503`: Recoverable key enrollment is temporarily unavailable. No key was created for a first attempt; a failed replay never mints a replacement.

---

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