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

# Create an API key

`POST /auth/api-keys`

## Request

- Base URL: `https://api.receiptor.ai/v1`
- URL: `https://api.receiptor.ai/v1/auth/api-keys`
- Auth: HTTP bearer

Create a key using an authenticated account session. Permissions default to ["all"]. Use "read-only" to store all currently known read grants, or supply an explicit grant array. Unknown grants are rejected. Permissions are immutable; create a replacement key to change them. Only active can be changed through PATCH /auth/api-keys/{apiKeyId}.

## Request body

- object
  - `name` string, required
  - `workspaceScope` 'all' | 'current'
  - `permissions` union
    - 'read-only'
    - string[]

## Response `200`

Successful response

- object
  - `success` boolean
  - `code` integer
  - `data` ApiKey
    - `_id` string
    - `name` string
    - `key` string: Full credential only on creation; masked in lists.
    - `workspaceScope` 'all' | 'current'
    - `orgId` string, nullable
    - `active` boolean
    - `permissions` string[]
    - `createdAt` string, date-time
    - `lastUsed` string, date-time

## Other responses

- `400`: Invalid input
- `401`: Authentication required

## Changes

- **2026-10-25** `a2d8aea5337a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/receiptor/apis/receiptor-ai-api/changes/auth/api-keys/post.md)

---

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