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

# Create an API key

`POST /v1/account/keys`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/account/keys`
- Auth: HTTP bearer

Mints a new scoped key for the caller's own customer. The raw `key`
value is returned ONCE and is never retrievable again — store it
immediately. Requires the `write` scope.

## Request body

- object
  - `name` string, required
  - `scopes` string[]: Subset of: extract, read, write, operations, billing, delivery, usage, records_write. Defaults to the calling key's own scopes. Every requested scope must already be held by the calling key; requesting one it lacks is rejected with `403` (`scope_not_grantable`) — a key can only ever narrow its own privilege on a newly minted key, never widen it. `usage`, `records_write` and `billing` are granted de novo only through owner+ key management, never through self-serve key creation.

## Response `201`

Newly created key. The `key` field is shown only here.

- object
  - `id` string, uuid
  - `name` string
  - `key` string: The raw secret. Shown once. Never returned again.
  - `masked_prefix` string
  - `scopes` string[]
  - `created_at` string, date-time
  - `warning` string

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `403`: The API key does not have the required scope.
- `429`: Daily rate limit exceeded.

---

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