---
title: "Create an API user"
method: POST
path: "/api-users"
tags: ["Users"]
---

# Create an API user

`POST /api-users`

Create a new API user (a non-human account intended to
authenticate integrations) within the caller's organisation.
The new user is attached to the supplied `site_id`, given the
organisation's default API role, has their email pre-verified,
and is issued a personal access token in the response — store
it securely because Trybe will never return it again.

Requires the caller's site-user to hold the `users:manage`
permission on the target site. The `name` must be unique
across API users in the organisation.

## Request body

- object
  - `name` string, required — Human-readable label for the API user. Shown in the API users list and recorded against audit-log entries so operators can identify which integration made a change. Pick something descriptive like "Mailchimp sync" or "POS terminal 3". Must be unique across API users in the organisation.
  - `site_id` string, uuid, required — Identifier of the site to attach the new API user to. The caller must hold the `users:manage` permission on this site; the user inherits the organisation that owns the site. Additional sites can be granted later by an organisation admin.

## Response `200`

A newly created API user, including the access token. The
`token` field is only returned on the create response — it is
not persisted by Trybe in a retrievable form, so store it
securely as soon as you receive it.

- object — Single-item envelope mixin. `allOf` this into any show response that wraps its `data` payload in an outer object; the concrete schema (e.g. `ShowUser`) adds its own `data` property with the appropriate `$ref` and keeps its own title so the SDK surface is unchanged.
  - `data` ApiUserWithToken, required — An API user augmented with a freshly-minted personal access token. Only returned by `createApiUser`; the token is not stored in a retrievable form and cannot be looked up later.
    - `id` string, uuid, required — The ID of the user
    - `name` string, required — The user's name
    - `organisation_name` string — The name of the organisation that this user belongs to
    - `organisation_id` string, uuid, required — The ID of the organisation that this user belongs to
    - `site_ids` string[], required — The IDs of the sites that this user belongs to
    - `status` string, required — The status of the user
    - `created_at` string, date-time, required — The date and time the user was created
    - `updated_at` string, date-time, required — The date and time the user was last updated
    - `token` string, required — Bearer token to authenticate as the new API user. Returned once on create; store it securely. If lost, generate a new one via the admin API-user regenerate-token endpoint.

## Other responses

- `401` — The user is unauthenticated
- `403` — The authenticated user does not have permission.
- `422` — The request didn't pass validation

---

[API](https://skmtc.dev/try/apis/trybe-api.md) · [All operations](https://skmtc.dev/try/apis/trybe-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/try/trybe-api/revisions/f37f92702da5/schema)