---
title: "Create an API key in the credential's mode, optionally with a name. With `replaceSameName`, the active keys of the mode with that exact name are revoked first, so an app that connects again keeps one key. A live key can be created only by an owner of the organization, signed in with a session and `X-Evictions-Mode: live` (403 `forbidden` otherwise, also for a live API key); at most 10 active keys per mode, counted after any replaced keys (409 `key_limit`, and then nothing is revoked)"
method: POST
path: "/v1/api-keys"
---

# Create an API key in the credential's mode, optionally with a name. With \`replaceSameName\`, the active keys of the mode with that exact name are revoked first, so an app that connects again keeps one key. A live key can be created only by an owner of the organization, signed in with a session and \`X-Evictions-Mode: live\` (403 \`forbidden\` otherwise, also for a live API key); at most 10 active keys per mode, counted after any replaced keys (409 \`key_limit\`, and then nothing is revoked)

`POST /v1/api-keys`

## Request

- Base URL: `https://api.evictionsapi.com`
- URL: `https://api.evictionsapi.com/v1/api-keys`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

## Request body

- object
  - `name` string
  - `replaceSameName` boolean

## Response `201`

The new key. The secret appears in this response only. An `Idempotency-Key` header is ignored: every request creates a key, and no response is stored or replayed.

- object
  - `id` string, required
  - `mode` 'test' | 'live', required
  - `name` string, nullable, required
  - `secret` string, required: The API key (`eak_test_...` or `eak_live_...`), shown here only.
  - `replaced` string[], required: The ids of the keys revoked by `replaceSameName`; empty otherwise.

## Other responses

- `400`: The request is invalid.
- `401`: The credential is missing or invalid.
- `403`: The credential is not allowed to do this (`forbidden`). For a signed-in session: `permission_denied`, the person's role in the organization lacks the permission this needs (ask an owner); `no_organization`, the person belongs to no organization yet (start one with `POST /v1/me/organizations` or accept an invitation).
- `404`: Not found.
- `409`: The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
- `422`: The case did not pass a check.

---

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