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

# Create an API key

`POST /v1/api-keys`

## Request

- Base URL: `https://api.recruitmcp.com`
- URL: `https://api.recruitmcp.com/v1/api-keys`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://recruitmcp.com/oauth/authorize`, token URL `https://recruitmcp.com/oauth/token`, scopes: `account:manage`)

A key never gets more scopes, a higher daily cap, or a higher approval threshold than the key that creates it. Omitted scopes copy the caller. Do not put account:manage or billing:manage on an agent key. Set customer_id to bind the key to one customer. approval_threshold_credits null or omitted means no HTTP threshold and 500 credits on MCP. approval_threshold_enrollments null or omitted means no HTTP threshold and 25 scheduled enrollments on MCP. The key pins the RecruitMCP-Version sent with this request, or the current version.

Scope: `account:manage`. Acts on the account; keys bound to a customer are refused.

## Headers

- `Idempotency-Key` string
- `RecruitMCP-Version` '2026-10-13'

## Request body

- object
  - `name` string
  - `scopes` string[]: Default: every scope of the calling key.
  - `daily_cap_credits` number, nullable: Credits this key may spend per UTC day.
  - `approval_threshold_credits` integer, nullable: Search, profile, company, and contact calls above this estimate return approval_required. Null means unset.
  - `approval_threshold_enrollments` integer, nullable: An enrollment whose summary.scheduled is above this returns approval_required. Null means unset.
  - `customer_id` string, nullable
  - `expires_at` string, date-time, nullable

## Response `201`

Created. The secret is shown once.

- ApiKeyCreated
  - `id` string, required
  - `object` 'api_key', required
  - `name` string, nullable
  - `prefix` string, required
  - `kind` 'secret' | 'oauth'
  - `scopes` string[], required
  - `customer_id` string, nullable: Keys bound to a customer always act inside it.
  - `daily_cap_credits` integer, nullable
  - `approval_threshold_credits` integer, nullable: Null when unset. HTTP then has no threshold. MCP uses 500 credits.
  - `approval_threshold_enrollments` integer, nullable: Null when unset. HTTP then has no enrollment threshold. MCP uses 25 scheduled enrollments.
  - `api_version` string: Pinned RecruitMCP-Version.
  - `created_at` string, date-time, required
  - `last_used_at` string, date-time, nullable
  - `expires_at` string, date-time, nullable
  - `api_key` string, required: The secret. Shown once.

## Other responses

- `400`: `invalid_request` (do not retry): A field is missing or has a value this endpoint does not accept. `unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.
- `401`: `unauthorized` (do not retry): Missing bearer API key.
- `403`: `forbidden` (do not retry): This route acts on the account. Keys bound to a customer cannot use it. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.
- `429`: `rate_limited` (retry): Per-key rate limit exceeded.

## Changes

- **2026-10-20** `ad27b35513a6`: 4 warning
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `400`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `401`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `403`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `429`

[Operation history](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/changes/v1/api-keys/post.md)

---

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