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

# Create API key

`POST /v1/api-keys`

## Request

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

Creates a new API key. Provide `name`, `permissions` (a list of `resource.action` strings, or `"all"`), and an optional `nodeId` to restrict the key to one location and everything beneath it. The raw key secret is returned exactly once, in this response; only its hash is stored afterward, so it cannot be retrieved again.

## Request body

- object
  - `name` string, required
  - `permissions` union: You must hold each one where the key applies. Default `[]` (a key that can do nothing).
    - 'all'
    - string[]
  - `nodeId` string, nullable: Pin the key to this location. Omit for a workspace-wide key, which needs its permissions workspace-wide.
  - `expiresInDays` number, nullable: Days until the key stops working (at most 3650). Omit, null or 0 = never expires.

## Response `201`

Success.

- object
  - `data` object, required
    - `id` string, required
    - `name` string, required
    - `preview` string, required: The first characters of the key (`ak_us_live_Ab3x`), to recognise it. Not usable as a credential.
    - `permissions` union, required: `resource.action` permissions, or `"all"` (every permission, now and later).
      - 'all'
      - string[]
    - `nodeId` string, nullable, required: The location the key is pinned to (it can act only there and below). Null = workspace-wide.
    - `lastUsedAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `expiresAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `expired` boolean, required
    - `revokedAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `createdAt` string, required: ISO-8601 timestamp (UTC).
    - `secret` string, required: The full key. Shown ONLY in this response; store it now. Send it as `Authorization: Bearer <secret>`.

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: You do not hold every permission you grant, or not at the key's location (a workspace-wide key needs them workspace-wide). Also refused for a Brix support session.
- `422`: `name` missing, `expiresInDays` over 3650 or not a number, or `nodeId` not a location of this workspace.
- `5XX`: Server error. The body carries a `requestId` to quote to support.

---

[API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/02fd3665dc7d?raw)