---
title: "Create a new API Key"
method: POST
path: "/auth/api-key"
tags: ["auth"]
---

# Create a new API Key

`POST /auth/api-key`

API Keys are simple randomly generated strings bound to roles that grant access to resources.

Every API Key maps to attributes defining its validity and can be revoked at any time.

API Key can be passed in the **X-API-Key** HTTP Header and in the querystring **&api_key=**


**Permission required:** edit_backend_settings

## Headers

- `X-Fields` string, mask

## Request body

- APIKeyRequest
  - `active` boolean — Is the API Key active or not
  - `expire_at` string, date-time — Expiration date
  - `roles` TokenRoleModel[], required — Roles to grant to this token bearer
    - `document_id` string — limited to a document
    - `inbox` string
    - `role` string, required
  - `user` string, required — User to give to the bearer

## Response `201`

Success

- APIKeyModel
  - `active` boolean, required — Is the API Key active or not
  - `expire_at` string, date-time — The date at which the API Key will expire
  - `roles` TokenRoleModel[] — the user roles
    - `document_id` string — limited to a document
    - `inbox` string
    - `role` string, required
  - `token` string, required — Token value
  - `user` string, required — Bearer user

## Other responses

- `403` — Permission insufficient
- `404` — Role not found

---

[API](https://skmtc.net/contractp/apis/contract-p.md) · [All operations](https://skmtc.net/contractp/apis/contract-p/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/contractp/contract-p/revisions/8ce53ebd6bd3/schema)