---
title: "Create user"
method: POST
path: "/api/v1/organizations/{organizationID}/users"
tags: ["Users"]
---

# Create user

`POST /api/v1/organizations/{organizationID}/users`

Creates a new user and associates with a set of groups.

## Request body

- UserWrite — A user create/update object.
  - `metadata` ResourceMetadata — Metadata required for all API resource reads and writes.
    - `name` string, required — A valid Kubernetes label value, typically used for resource names that can be indexed in the database.
    - `description` string — The resource description, this optionally augments the name with more context.
    - `tags` Tag[] — A list of tags.
      - `name` string, required — A unique tag name.
      - `value` string, required — The value of the tag.
  - `spec` UserSpec, required — A user specification.
    - `subject` string, required — The user's canonical name, usually an email address.
    - `state` 'active' | 'pending' | 'suspended', required — The state a user is in.
    - `groupIDs` string[], required — A list of group IDs.

## Response `201`

A user.

- UserRead — A user read object.
  - `metadata` OrganizationScopedResourceReadMetadata, required — Metadata required for all API resource reads and writes.
    - `name` string, required — A valid Kubernetes label value, typically used for resource names that can be indexed in the database.
    - `description` string — The resource description, this optionally augments the name with more context.
    - `tags` Tag[] — A list of tags.
      - `name` string, required — A unique tag name.
      - `value` string, required — The value of the tag.
    - `id` string, required — The unique resource ID.
    - `creationTime` string, date-time, required — The time the resource was created.
    - `createdBy` string — The user who created the resource.
    - `modifiedTime` string, date-time — The time a resource was updated.
    - `modifiedBy` string — The user who updated the resource.
    - `deletionTime` string, date-time — The time the resource was deleted.
    - `provisioningStatus` 'unknown' | 'provisioning' | 'provisioned' | 'deprovisioning' | 'error', required — The provisioning state of a resource.
    - `healthStatus` 'unknown' | 'healthy' | 'degraded' | 'error', required — The health state of a resource.
    - `organizationId` string, required — The organization identifier the resource belongs to.
  - `spec` UserSpec, required — A user specification.
    - `subject` string, required — The user's canonical name, usually an email address.
    - `state` 'active' | 'pending' | 'suspended', required — The state a user is in.
    - `groupIDs` string[], required — A list of group IDs.
  - `status` UserStatus, required — Additional user metadata.
    - `lastActive` string, date-time — The last time a user performed some action. This is not guaranteed to be completely accurate depending on performance constraints.

## Other responses

- `401` — Authentication failed or the access token has expired.
- `403` — Request was denied by authorization, this may be caused by the authorization token not having the required scope for an API, or the user doesn't have the necessary privileges on the provider platform.
- `409` — Resource conflicts with another, usually this means they have the same name.
- `500` — An unexpected or unhandled error occurred. This may be a transient error and may succeed on a retry. If this isn't the case, please report it as an issue.

---

[API](https://skmtc.net/nscale/apis/region-service-api.md) · [All operations](https://skmtc.net/nscale/apis/region-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nscale/region-service-api/revisions/c2991b23da6e/schema)