Create API Key

POST /v1/keys — Create a new API key. Returns the raw key exactly once.

Endpoint

POST /v1/keys

Authentication: Requires X-Admin-Key header (not a regular API key). The admin key must match the ADMIN_API_KEY environment variable on the server.

---

Request Headers

Header	Required	Description
X-Admin-Key	Yes	The master admin key
Content-Type	Yes	Must be application/json

Request Body

Field	Type	Required	Default	Description
name	string	Yes	—	Human-readable name for this key (1-255 characters)
rate_limit_rpm	integer	No	100	Requests per minute limit (1-10,000)

---

Example Request

curl -X POST https://spendguardapi.com/v1/keys \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: your-admin-key" \
  -d '{
    "name": "Production Agent Key"
  }'

---

Response — 201 Created

{
  "key_id": "key_a1b2c3d4e5f6",
  "name": "Production Agent Key",
  "api_key": "sg_live_4a8f2c1b9e7d3056ef28a1c4b7e93f1d4a8f2c1b9e7d3056ef28a1c4b7e93f1d",
  "rate_limit_rpm": 100,
  "created_at": "2026-04-03T12:00:00Z"
}

The api_key field contains the raw API key. This is shown exactly once. SpendGuard stores only a SHA-256 hash of the key — the original cannot be retrieved. Copy it immediately and store it securely.

---

Error Responses

Status	Code	When
401	unauthorized	Missing, invalid, or wrong admin key
422	validation_error	Missing name or invalid rate_limit_rpm
500	internal_error	Server error