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

# Create an API key

`POST /v1/api-keys`

## Request

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

Creates an API key and returns its secret once. Send the secret as a Bearer token to the REST API or any Pomerado MCP.

- A key carries only permissions you hold. It gets api_keys:manage, billing:manage or team:manage only when permissions names them.
- It expires after 90 days unless expires_in_days says otherwise.
- With deliver "dashboard", nothing is created yet: this returns a Dashboard link where the person creates the key and sees the secret, so it never reaches this client.
- With purpose "connect", for the Connect page: it revokes your older unused connect keys for the same integration (or for the account) beyond three, and at your key limit your oldest unused connect key, so these keys never fill your limit. A key that has been used is never revoked this way, and you can create at most 20 connect keys an hour.

## Request body

- object
  - `name` string, required: 1 to 100 characters, without leading or trailing spaces
  - `permissions` string[]: Permissions the key carries, each one you hold. Default: all you hold except api_keys:manage, billing:manage and team:manage
  - `integration_id` string: an integration ID: int_ and 32 lowercase hex digits
  - `expires_in_days` integer: an integer
  - `deliver` 'dashboard': Return a Dashboard link instead of the secret, so the secret never reaches this client
  - `purpose` 'connect': connect: a key the Connect page makes for an agent. Creating one revokes your older unused connect keys for the same integration (or for the account) beyond three, and at your key limit your oldest unused connect key; a key that has been used is never revoked this way. At most 20 connect keys an hour.

## Response `200`

With deliver dashboard: where to finish

- DashboardDelivery
  - `dashboard_url` string, required: A signed-in Dashboard page where the person finishes this and sees the secret once

## Other responses

- `201`: The new key and its one-time secret
- `400`: invalid_request
- `401`: unauthorized, reauthentication_required
- `403`: permission_not_held, forbidden
- `404`: not_found
- `409`: api_key_limit_reached
- `413`: request_too_large
- `429`: api_key_create_throttled
- `500`: internal_error
- `503`: temporarily_unavailable

---

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