Create an API key (admin)

POST

/api/keys

curl --request POST \
  --url https://example.com/api/keys \
  --header 'Content-Type: application/json' \
  --header 'Remote-User: <Remote-User>' \
  --data '{ "name": "example", "admin": true, "grants": [ { "kind": "group", "target": "example", "permissions": [ "publish" ] } ], "expires_at": "example" }'

• 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

Media typeapplication/json

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 read

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.

Media typeapplication/json

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 read

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

Example

{
  "grants": [
    {
      "kind": "group",
      "permissions": [
        "publish"
      ]
    }
  ]
}

400

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

Media typeapplication/json

object

error

required

string

Example^generated

{
  "error": "example"
}

401

Missing or invalid credentials.

Media typeapplication/json

object

error

required

string

Example^generated

{
  "error": "example"
}

403

Authenticated, but not permitted for this target/capability.

Media typeapplication/json

object

error

required

string

Example^generated

{
  "error": "example"
}