---
title: "Generate a free API key"
method: POST
path: "/v1/keys/generate"
tags: ["API Keys"]
---

# Generate a free API key

`POST /v1/keys/generate`

Generates a free API key with 200 requests/month quota (batch validation counts 1 request per IBAN). The first key issued to a network is instant. A repeat creation from the same network within 7 days must prove the mailbox is readable: that call answers 403 "verification_required" and mails a 6-digit code to the address supplied, and the SAME request is then repeated with a "code" field within 15 minutes. At most 3 keys per network per day. A caller that cannot receive mail does not need this endpoint at all: prepaid credits (POST /v1/credits/buy/1k) and x402 pay-per-call need no key.

## Request body

- object
  - `email` string, email, required — Email address for key registration
  - `code` string — Optional. The 6-digit code mailed after a 403 "verification_required". Repeat the same request with it within 15 minutes; omit it to be mailed a fresh one. The challenge locks after 5 wrong attempts.

## Response `201`

API key generated (shown only once)

## Other responses

- `400` — Body rejected before any key was considered. "error" is "invalid_json", "invalid_email", or "disposable_email" (the free tier needs a real, non-disposable mailbox).
- `403` — The mailbox must be verified. "verification_required": a 6-digit code was just mailed, repeat this exact request with "code" within 15 minutes. "verification_failed": the code was wrong or expired, and "reason" says which ("wrong_code", "expired", "no_challenge", "too_many_attempts"); request again without "code" to be sent a fresh one.
- `429` — Too many creations. "key_creation_limit": at most 3 free keys per network per day. "verification_rate_limited": too many codes were mailed to this address or from this network today. "rate_limited": one key per email per day. Existing keys keep working in every case.
- `503` — "verification_unavailable": the verification mail could not be sent right now, so no key was issued and no code is pending. Retry in a few minutes.

## Changes

- **2026-08-21** `4c17531422ec` — 3 info
  - added the new optional request property `code`
  - added the non-success response with the status `403`
  - added the non-success response with the status `503`

[Change history](https://skmtc.dev/ibanforge/apis/ibanforge-api/changes/v1/keys/generate/post.md)

---

[API](https://skmtc.dev/ibanforge/apis/ibanforge-api.md) · [All operations](https://skmtc.dev/ibanforge/apis/ibanforge-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ibanforge/ibanforge-api/revisions/9499dba434ea/schema)