UserService

POST /api/users

Changed on Oct 8, 2026

CreateUser creates a user. The first user of an instance becomes an admin. Otherwise, unless an admin calls it, the instance must allow user registration and password sign-up, and the new user gets the USER role.

Request

The document declares no server URL.
Auth
none declared

Query parameters

userIdstring

Optional. The resource ID to use for this user. If set, it must equal user.username and follow the username format. Format: ^a-zA-Z0-9?$

validateOnlyboolean

Optional. If set, validate the request but do not create the user.

requestIdstring

Optional. An idempotency token. Currently ignored.

Request body

namestring

Identifier. The resource name of the user. {user} is the username. Format: users/{user}

usernamestring required

Required. The unique username, used to sign in.

displayNamestring

Optional. The display name of the user.

emailstring

Optional. The email address of the user. Stored trimmed and lowercased; empty means no address. An address belongs to at most one user on the instance, so writes that would reuse one fail with ALREADY_EXISTS. Returned only to the user and to admins.

avatarUrlstring

Optional. The avatar URL of the user. An avatar set as a data URI (PNG, JPEG, GIF or WebP, at most 2 MiB) is returned as a file server URL.

descriptionstring

Optional. The description of the user.

passwordstring

Input only. The password of the user. Never returned.

role'ROLE_UNSPECIFIED' | 'ADMIN' | 'USER' enum required

Required. The role of the user. Only admins can change it.

state'STATE_UNSPECIFIED' | 'NORMAL' | 'ARCHIVED' enum required

Required. The state of the user. Only admins can change it.

createTimestring date-time

Output only. The creation timestamp.

updateTimestring date-time

Output only. The last update timestamp.

Response