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

# Create a scoped API key

`POST /api/v1/api-keys`

## Request

- Base URL: `https://www.poster.ly`
- URL: `https://www.poster.ly/api/v1/api-keys`
- Auth: HTTP bearer

Create a new posterly API key for the authenticated user after explicit confirmation. The calling token must be a dashboard-created API key with `accounts:write`. OAuth-issued tokens, managed assistant tokens, and session-authenticated requests cannot mint API keys. Requested scopes cannot exceed the scopes on the calling key. A teammate whose API access comes from a workspace owner gets a key bound to that workspace (pass `workspace_id` when there are several; otherwise `400 workspace_id_required`). Those keys count against the owner plan, per teammate per workspace, and the owner is emailed. The full key is returned once in the `key` field.

## Request body

- CreateApiKeyRequest
  - `name` string: Human-readable key name.
  - `scopes` ApiKeyScope[]: Scopes for the new key. Omit to copy the calling key scopes. Requested scopes cannot exceed the calling key scopes. billing:read and billing:write allow managing the posterly subscription (cancel/pause/resume/downgrade). review_links:write is never inherited and cannot be requested here: it is granted only when a person ticks "Create client portal sign-in links" in /dashboard/api. The same applies to members:read and members:write, granted only by the "Manage team" permission.
  - `workspace_id` string: Optional workspace restriction. Workspace-scoped calling keys cannot create keys outside their workspace.
  - `expires_in_days` integer: Optional expiry from now, up to 365 days. Omit for no expiry.
  - `confirm` true, required: Must be true after the user explicitly confirms that a new secret API key should be created.

## Response `201`

API key created successfully. Store the returned key securely; it will not be shown again.

- CreateApiKeyResponse
  - `key` string, required: Full API key. This is only returned once.
  - `api_key` ApiKeyResource, required
    - `id` string, required
    - `name` string, required
    - `key_prefix` string, required
    - `scopes` ApiKeyScope[], required
    - `workspace_id` string, nullable
    - `expires_at` string, date-time, nullable
    - `created_at` string, date-time, required
  - `warning` string
  - `limits` object
    - `tier` string
    - `max_user_keys` integer
    - `active_user_keys` integer
    - `remaining_user_keys` integer
    - `uses_grandfathered_keys` boolean

## Other responses

- `400`: Validation error
- `401`: Invalid or missing API key
- `403`: Request is authenticated but not allowed
- `429`: Too many requests

---

[API](https://skmtc.dev/poster/apis/posterly-api.md) · [All operations](https://skmtc.dev/poster/apis/posterly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/poster/apis/posterly-api/revisions/60be02a61f95?raw)