---
title: "Issue API key"
method: POST
path: "/accounts/api-key"
tags: ["API Keys"]
---

# Issue API key

`POST /accounts/api-key`

## Request

- Base URL: `https://api.quiva.ai`
- URL: `https://api.quiva.ai/accounts/api-key`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/quivaworks/apis/quiva-ai-gateway/docs/accounts/api-key/post.ts> (a function with typed inputs; its response is checked against the schema)

Issues a new API key. The full key is returned once. User keys act as the issuing user and work on every endpoint that user can reach. Account keys (`scope: account`) can be issued only by root and administrators. Keys expire after 90 days unless `expiry_days` says otherwise. This is not an API integration: integrations are machine identities for task sync only.

## Request body

- ApiKeyRequest
  - `key_name` string, required: API key name
  - `email` string, email: Issue the key for another user of the account (root and administrators only). Defaults to the caller.
  - `scope` 'user' | 'account': `user` keys act as the issuing user. `account` keys are shared by the account and can be issued only by root and administrators.
  - `expiry_days` integer: Days until the key expires. Defaults to 90. A negative value means the key does not expire.
  - `allow_endpoints` ApiKeyEndpoint[]: Restrict the key to these endpoints
    - `method` string, required: HTTP method
    - `path` string, required: HTTP path
    - `gateway_id` string
    - `subjects` string[]: Subjects allowed on the request body
  - `allow_sub_subjects` string[]
  - `deny_sub_subjects` string[]
  - `allow_pub_subjects` string[]
  - `deny_pub_subjects` string[]
  - `resp_permission` object: Response permission for request/reply
    - `max` integer
    - `ttl` integer: Nanoseconds

## Response `200`

API key created successfully

- object
  - `data` ApiKeyResponse, required: Returned once, on creation. The full key cannot be read again.
    - `key` string: API key
    - `name` string
    - `created_on` string, date-time
    - `expires_on` string, date-time
    - `creds` string: API credentials string for CLI use. Not returned for restricted keys.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden. Only root and administrators can issue account keys or keys for another user.

## Changes

- **2026-11-12** `700eb1ace61a`: 11 info
  - added the new optional request property `allow_endpoints`
  - added the new optional request property `allow_pub_subjects`
  - added the new optional request property `allow_sub_subjects`
  - added the new optional request property `deny_pub_subjects`
  - …7 more
- **2025-06-12** `4979dfd00eda`: 5 warning, 1 info
  - removed the optional property `created_on` from the response with the `200` status
  - removed the optional property `creds` from the response with the `200` status
  - removed the optional property `expires_on` from the response with the `200` status
  - removed the optional property `key` from the response with the `200` status
  - …2 more

[Operation history](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway/changes/accounts/api-key/post.md)

---

[API](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway.md) - [All operations](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway/llms.txt) - [OpenAPI document](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway/revisions/700eb1ace61a?raw)