---
title: "Create a new API key"
method: POST
path: "/api-keys"
tags: ["API Keys"]
---

# Create a new API key

`POST /api-keys`

## Request

- Base URL: `https://statusstack.com/api`
- URL: `https://statusstack.com/api/api-keys`
- Auth: HTTP bearer

Generate a new API key. The plain-text `token` is returned once, in this response,
and cannot be retrieved again.

## Request body

- object
  - `name` string, required: Descriptive name for the API key
  - `version` string: API version the key targets, `v` followed by a number.
  - `permissions` string[]: `read`, `write` and `delete` are open to every user. `admin`, `platform-admin` and `*` can only be granted by a super admin; anyone else gets a 422.
  - `expires_in_days` integer, nullable: Days until the key expires. Omit or send null for a key that never expires.
  - `team_id` string, uuid, nullable: Team the key is scoped to; the user must be a member. Omitted or null, the key is scoped to the user's current team.
  - `organization_id` string, uuid, nullable: Organization the key is scoped to; the user must belong to it and the team must be in it. Omitted, it is the team's organization.

## Response `201`

API key created successfully

- object
  - `data` object, required
    - `id` string, uuid, required
    - `name` string, required
    - `token` string, required: The plain-text API key. Shown only in this response.
    - `permissions` string[], required
    - `expires_at` string, date-time, nullable
    - `version` string, required
    - `created_at` string, date-time, required

## Other responses

- `401`: No valid Sanctum session or token. Laravel's own `{message}` body.
- `403`: The team's plan does not include API access (`{error}`), or the policy refused the user (`{message}`).
- `422`: Validation failed, or no team could be resolved, or the team is not in the given organization — the last two answer `{error}`.

---

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