---
title: "Create a new API key for the authenticated customer"
method: POST
path: "/v1/api-keys/"
tags: ["API Keys"]
---

# Create a new API key for the authenticated customer

`POST /v1/api-keys/`

## Request

- Base URL: `https://api.platform.soax.com`
- URL: `https://api.platform.soax.com/v1/api-keys/`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/soax/apis/soax-api/docs/v1/api-keys/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new API key. To prevent privilege escalation, the new key's `scopes` must be a subset of the calling key's scopes, and `package_ids` (if provided) must be a subset of the calling key's package restriction. If `package_ids` is omitted, the new key inherits the calling key's restriction.

The response includes the plaintext `secret` — this is the **only** time it is ever returned. Store it immediately in a secure location.

Requires the `api-keys:write` scope.

## Request body

- CreateApiKeyRequest: Request schema for POST /v1/api-keys endpoint.
  - `name` string, required: Human-readable name for the key (shown in the dashboard and key listings).
  - `scopes` string[], required: Scopes to grant. Must be a subset of the calling key's own scopes.
  - `package_ids` string[], nullable: Optional list of package IDs the key is restricted to. Must be a subset of the calling key's own restriction. Omit to inherit the calling key's restriction; `null` on an unrestricted caller creates an unrestricted key.

## Response `201`

Successful Response

- CreateApiKeyResponse: Response schema for POST /v1/api-keys endpoint. Includes the plaintext secret, which is only revealed at creation time and can never be retrieved again. The secret should be immediately stored by the client in a secure location.
  - `id` string, required
  - `name` string, required
  - `scopes` string[], required
  - `package_ids` string[], nullable, required
  - `secret` string, required
  - `created_at` string, date-time, required

## Other responses

- `400`: A parameter value or combination is invalid. Service-level validation errors use the `error` key; endpoint-level checks use `detail`. Read `detail ?? error`.
- `401`: Missing, invalid, or revoked API key.
- `403`: The API key does not carry the scope this endpoint requires.
- `422`: Validation Error
- `429`: Rate limit exceeded (5 requests/second per API key, 500 requests/minute per IP). The response includes `Retry-After` (seconds), `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (Unix time) headers — wait `Retry-After` seconds and retry.

---

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