Create an API key (admin)

POST

/api/keys

• Your gotifacts apex (canonical base domain), fronted by your reverse proxy. Any configured alias domains serve the same API and sites, but responses (e.g. base_domain) always report the canonical domain.

Returns the plaintext token once in the key field. The legacy {name, scope, group} body is still accepted for backward compatibility.

Authorizations

• forwardAuth

Request Body^required

object

name

required

string

admin

boolean

grants

Array<object>

object

kind

required

string

Allowed values: group site

target

required

A group path (e.g. docs, empty = all sites) or a group/slug for a single site.

string

permissions

required

Array<string>

Allowed values: publish unpublish rollback patch purge

expires_at

RFC3339 instant or YYYY-MM-DD. Omit for a key that never expires.

string

Responses

201

The created key, including its plaintext token.

object

id

required

integer format: int64

name

required

string

admin

required

boolean

grants

required

Array<object>

object

kind

required

string

Allowed values: group site

target

required

A group path (e.g. docs, empty = all sites) or a group/slug for a single site.

string

permissions

required

Array<string>

Allowed values: publish unpublish rollback patch purge

created_at

required

string format: date-time

last_used_at

string format: date-time

expires_at

string format: date-time

key

required

The plaintext token (gtf_…). Shown only once, at creation.

string

400

Invalid request (bad path, malformed body, or missing content).

object

error

required

string

401

Missing or invalid credentials.

object

error

required

string

403

Authenticated, but not permitted for this target/capability.

object

error

required

string