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

# Create an API key

`POST /v1/keys`

## Request

- Base URL: `https://dnsmint.com/api`
- URL: `https://dnsmint.com/api/v1/keys`
- Auth: HTTP bearer

Mint a key. The secret is returned once, in this response, and cannot be retrieved afterwards. Requires the keys:write scope. A key can only grant within its own reach: a key narrowed to one domain cannot create a team-wide key, or reach a domain it does not hold. keys:write cannot be combined with dns01:write on one key. A key carrying hostnames:write may grant dns01:write on a hostname it reaches without holding it, which is how a per-machine renewal credential is minted; that grant must name a hostname, so no domain-wide or team-wide DNS-01 key can be created through the API.

## Request body

- CreateKeyRequest
  - `name` string
  - `scopes` union[]: Scope strings for the whole team, or objects narrowing one to a domain or hostname. Omit for the three hostname and DNS-01 scopes on the whole team; keys:write is never included by default and must be named.
    - union
      - string
      - object
        - `scope` string
        - `domain` string
        - `hostname` string
  - `expires_in_days` integer, nullable: Days until the key stops working. Null or omitted for a key that does not expire.

## Response `201`

Created. Contains the only copy of the secret.

- CreatedApiKey: A key as seen from outside. Never contains the secret.
  - `key_id` string: The id half of dnsm_<key_id>_<secret>.
  - `name` string
  - `scopes` object[]
    - `scope` 'hostnames:read' | 'hostnames:write' | 'dns01:write' | 'keys:write'
    - `on` string: The domain or hostname this scope is narrowed to. Absent means the whole team.
  - `created_at` string, date-time
  - `last_used_at` string, date-time, nullable
  - `expires_at` string, date-time, nullable: Null for a key that does not expire.
  - `created_by_key_id` string, nullable: The key that minted this one, or null when a person created it in the dashboard.
  - `expired` boolean
  - `key` string, required: The full secret, dnsm_<key_id>_<secret>. Returned only here and never retrievable again.

## Other responses

- `400`: Invalid scopes, an escalation attempt, or the key cap reached
- `401`: Missing, invalid or expired key
- `403`: Key does not carry keys:write

---

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