---
title: "Issue a self-serve API key"
method: POST
path: "/api/v1/keys"
tags: ["Onboarding"]
---

# Issue a self-serve API key

`POST /api/v1/keys`

## Request

- Base URL: `https://www.adadiamonds.com`
- URL: `https://www.adadiamonds.com/api/v1/keys`
- Auth: none required

Returns a working API key immediately, with no account and no human approval. Keys are limited to the public read scopes and mainly buy a higher rate limit; the key is shown once and stored only as a hash, so save it. Request `env: "sandbox"` to get a key whose writes are acknowledged and discarded.

## Request body

- ApiKeyRequest
  - `name` string, required: A short label for this key.
  - `env` 'sandbox' | 'production'
  - `scopes` string[]
  - `contact_email` string, email

## Response `201`

The key. Store it now; it is not retrievable.

- ApiKey
  - `object` 'api_key', required
  - `api_key` string, required: Shown once. Store it.
  - `key_id` string, required
  - `name` string
  - `scopes` string[], required
  - `env` 'sandbox' | 'production', required
  - `usage` string
  - `documentation_url` string, uri

## Other responses

- `400`: The request was malformed. `error_description` says which field.
- `403`: The credential is valid but lacks the required scope, or the scope cannot be self-issued.
- `429`: Over the rate limit. Wait `Retry-After` seconds; a credential raises the limit.

---

[API](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api.md) · [All operations](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api/revisions/2b2ed3201815?raw)