---
title: "Create a new API user"
method: POST
path: "/v2/api-users"
tags: ["API User"]
---

# Create a new API user

`POST /v2/api-users`

Creates a new API user (also known as a machine user) that your application
can use to authenticate with Spotnana APIs. Each API user is scoped to a specific TMC and role,
giving you control over what level of access the credentials grant.

**Use this endpoint to:**
- Generate a dedicated `clientId` and `clientSecret` pair that your backend services can use to obtain access tokens.
- Assign either a TMC admin or a company admin role to scope what the API user can do across your organization.
- Create a SCIM API user by setting `credentialType` to `SCIM_TOKEN` with `role` set to `COMPANY_ADMIN`. This returns a SCIM bearer token instead of a client secret.

**Next steps:**
- For `CLIENT_CREDENTIALS` (default): Use the `clientId` and `clientSecret` in the `POST /v2/auth/oauth2-token` endpoint to obtain an access token.
- For `SCIM_TOKEN`: Use the returned `scimToken` as the Bearer token in the `Authorization` header for SCIM API requests (`/v2/scim/Users`, etc.).

**Notes:**
- Store the `clientSecret` or `scimToken` securely. They are only returned once at creation and cannot be retrieved later.
- You can create up to 5 API users per TMC. To increase this limit, contact your Spotnana representative.
- Only a TMC admin can use this endpoint to create API users.
- `SCIM_TOKEN` credential type requires `role` to be `COMPANY_ADMIN`.

## Request body

- CreateApiUsersRequest
  - `tmcId` string — Tmc id
  - `orgId` string — Org id
  - `role` 'TMC_ADMIN' | 'COMPANY_ADMIN' — Roles supported for api user creation
  - `credentialType` 'CLIENT_CREDENTIALS' | 'SCIM_TOKEN' — Type of credentials to generate for the API user. Defaults to CLIENT_CREDENTIALS.

## Response `200`

User created successfully

- CreateApiUsersResponse
  - `clientId` string — Api user client id
  - `clientSecret` string — Api user client secret. Present for CLIENT_CREDENTIALS credential type.
  - `scimToken` string — SCIM bearer token (Base64-encoded JSON envelope with encrypted secret). Present only for SCIM_TOKEN credential type.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `409` — Max users for this tmcId already exist

---

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