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

# Create an API key

`POST /api/v1/keys`

## Request

- Base URL: `https://spoofy.social`
- URL: `https://spoofy.social/api/v1/keys`
- Auth: API key in cookie `better-auth.session_token`

Every field is optional. `scopes: ["read"]` makes a read-only key. Caps are USD strings; `platforms` limits which platforms the key may order for; `allowedIps` limits where it can be used from (addresses or CIDR ranges, up to 20). The full key is in this answer only — store it now. Up to 20 active keys.

## Request body

- object
  - `name` string
  - `scopes` string[]
  - `dailyCap` string, nullable
  - `perOrderCap` string, nullable
  - `platforms` string[]
  - `allowedIps` string[]: Optional: the key works only from these addresses or CIDR ranges.
  - `mode` 'live' | 'test': test: a key that starts spoofy_test_ and answers every spend as a dry run.

## Response `201`

Created. `key` is shown once.

- object
  - `key` string
  - `apiKey` ApiKey
    - `id` string
    - `name` string
    - `prefix` string: First characters of the key, to tell keys apart.
    - `mode` 'live' | 'test': test: every spend answers as a dry run (the real price, checks and balance; nothing charged or sent); cancelling and pausing are refused.
    - `scopes` string[]
    - `dailyCap` string, nullable: Max USD spent per UTC day (net of refunds); null = no cap.
    - `perOrderCap` string, nullable: Max USD per order; null = no cap.
    - `platforms` string[]: Allowed platforms; empty = all.
    - `allowedIps` string[]: Addresses or CIDR ranges the key works from; empty = anywhere.
    - `lastUsedAt` string, date-time, nullable
    - `lastUsedIp` string, nullable: The address it was last used from.
    - `createdAt` string, date-time
    - `revokedAt` string, date-time, nullable

## Other responses

- `400`: The request is not valid. `error.message` says why.
- `401`: No valid API key or session.
- `409`: A limit was reached.
- `413`: The request body is too big (uploads up to 4 MB, everything else up to 64 KB).
- `429`: Slow down: too many requests in a short time. Wait `Retry-After` seconds and carry on.

---

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