Forgejo API
POST/admin/users

Create a user account

Creates a new user account with the supplied identity, login, notification, access, and visibility settings. Provide username and email at minimum; you can also set migration metadata such as created_at and account options such as restricted or must_change_password. A 201 response returns the created user object.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

11 body fields

User account creation options, including the required username and email and optional account settings.

created_atstringoptional
For explicitly setting the user creation timestamp. Useful when users are migrated from other systems. When omitted, the user's creation timestamp will be set to "now".
emailstringrequired
The user's email address in valid email format.
full_namestringoptional
The user's full name.
login_namestringoptional
The user's login name.
must_change_passwordbooleanoptional
Whether the user must change the password at the next sign-in.
passwordstringoptional
The password for the new user account.
restrictedbooleanoptional
Whether the new account has restricted access.
send_notifybooleanoptional
Whether to send a notification to the new user.
source_idintegeroptional
The integer identifier of the login source for the account.
usernamestringrequired
The username for the new user account.
visibilitystringoptional
The visibility setting for the new user account.

4 status codes
201Returns the created user object, including its identifier, username, email, account status, profile details, and timestamps.
activebooleanoptional
Is user active
avatar_urlstringoptional
URL to the user's avatar
createdstringoptional
descriptionstringoptional
the user's description
emailstringoptional
followers_countintegeroptional
user counts
following_countintegeroptional
full_namestringoptional
the user's full name
html_urlstringoptional
URL to the user's profile page
idintegeroptional
the user's id
is_adminbooleanoptional
Is the user an administrator
languagestringoptional
User locale
last_loginstringoptional
locationstringoptional
the user's location
loginstringoptional
the user's username
login_namestringoptional
the user's authentication sign-in name.
Default:empty
prohibit_loginbooleanoptional
Is user login prohibited
pronounsstringoptional
the user's pronouns
restrictedbooleanoptional
Is user restricted
source_idintegeroptional
The ID of the user's Authentication Source
starred_repos_countintegeroptional
visibilitystringoptional
User visibility level option: public, limited, private
websitestringoptional
the user's website
400Returned when the request is malformed or cannot be parsed as user creation options.
messagestringoptional
urlstringoptional
403Returned when the authenticated user is not permitted to create user accounts.
messagestringoptional
urlstringoptional
422Returned when a required field is missing or a supplied user value fails validation.
messagestringoptional
urlstringoptional

Error handling

A 400 is returned when the request is malformed, a 403 when the authenticated user is not permitted to create accounts, and a 422 when the supplied values fail validation. username and email are required, and email must use a valid email format; created_at must be an ISO 8601 date-time when provided.