---
title: "Create an API key"
method: POST
path: "/client/keys"
tags: ["Keys"]
---

# Create an API key

`POST /client/keys`

## Request

- Base URL: `https://api.roar-ai.com`
- URL: `https://api.roar-ai.com/client/keys`
- Auth: HTTP bearer

Returns the plaintext key ONCE. Granting management scopes requires an owner session or a key that already holds them. A key cannot create a key in a project whose tool bundles run with full access (403) — its tools would run without approval; an owner or admin in the console can. Requires `keys:write`.

## Request body

- CreateKeyRequest
  - `name` string
  - `projectId` string, uuid, nullable
  - `scopes` string[]
  - `expiresInDays` integer
  - `spendLimitUsd` number, nullable
  - `budgetPeriod` 'day' | 'week' | 'month' | 'total'

## Response `201`

The created key (plaintext shown once)

- CreatedKey
  - `id` string, uuid, required
  - `name` string, nullable, required
  - `prefix` string, required: The visible head of the key — enough to identify it, never enough to use it
  - `projectId` string, uuid, nullable, required
  - `scopes` string[], required
  - `expiresAt` string, date-time, nullable, required
  - `createdAt` string, date-time, required
  - `key` string, required: Plaintext — shown once
  - `baseUrl` string, required: The OpenAI-compatible endpoint this key is used against
  - `warning` string, required

## Other responses

- `401`: Unauthenticated
- `403`: Key lacks keys:write / cannot escalate scopes

---

[API](https://skmtc.dev/roar-ai/apis/roar-ai-api.md) · [All operations](https://skmtc.dev/roar-ai/apis/roar-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/roar-ai/apis/roar-ai-api/revisions/37e4d0d5a7fe?raw)