---
search:
  tags:
    - API Keys
    - POST
seo:
  description: >-
    Persists a new API key from a caller-supplied public key. The caller
    generates (or already… Reference for the POST /api_keys endpoint in the REST
    API API.
sidebar:
  badge: POST
  label: Create an API Key
title: Create an API Key
type: openapi-operation
---
Persists a new API key from a caller-supplied public key. The caller generates (or already holds) the keypair — UDX never receives the private key. The public key must be RSA with a modulus between 2048 and 4096 bits, inclusive.

### Endpoint

- Method and path: `POST /api_keys`
- Operation ID: `createAPIKey`
- API reference: [POST /api_keys](/api-reference/api-keys/createapikey)

#### Authorization

- Accepted credentials: `UDX-Access-Key` header and `UDX-Access-Timestamp` header and `UDX-Access-Signature` header; or Bearer token in `Authorization`
- Details: [Authentication](/authentication)

#### Parameters

- `UDX-Version` (`header`) — Dated API version (YYYY-MM-DD). Omit to use the oldest supported version. An unknown version returns `400`.
- `UDX-Idempotency-Key` (`header`) — Optional client-generated key that makes a mutation safe to retry. Reuse it only for a byte-identical retry. When present, it is included in the request signature; omitting it disables UDX idempotency for that request.

#### Request body

- Content type: `application/json`
- Schema: `CreateAPIKeyRequest`
- Required: yes
- Fields:
  - `name` (string, required) — A nickname for the new key, so you can tell your keys apart later.
  - `public_key` (string, required) — PEM-encoded RSA public key. Rejected with 400 if it isn't a single well-formed PEM block containing a PKIX-encoded RSA public key with a modulus between 2048 and 4096 bits, inclusive.
  - `scopes` (array, required) — The permissions to grant this key. Fixed for its lifetime — granting a different set of scopes later means creating a new key and revoking this one.
  - `account_id` — Restricts the key to a single account by its opaque public identifier. Omit (or null) to leave the key unrestricted, usable against every account accessible to the caller. Rejected with 403 if the caller cannot access the given account.

#### Responses

- `201` — The created API key's metadata.
- `400` — Request doesn't conform to this spec.
- `401` — No valid credential was provided.
- `403` — The caller cannot access `account_id`, or the credential lacks the `keys:manage` scope.
- `409` — This key is still in use or its response cannot be replayed. The mutation may have run; check `detail` before retrying.
- `422` — This key belongs to a different request.
- `429` — The Member's request rate is exhausted. Wait for `Retry-After`.
- `500` — Something went wrong on UDX's side.
- `503` — Request admission is unavailable. Retry later.