Skip to main content
The User Management APIs provide endpoints for creating, updating and managing users, their permissions, roles, and authentication settings.

​
Users

​
List Users

Retrieve a paginated list of users with optional filtering. 
curl -X GET "http://localhost:8091/apis/api.console.halo.run/v1alpha1/users?page=0&size=20" \
  -H "Authorization: Bearer {token}"
​
page
integer
default:"0"
Page number. Default is 0.
​
size
integer
default:"0"
Size number. Default is 0.
​
keyword
string
Keyword to search users
​
role
string
Filter users by role name
​
labelSelector
array
Label selector. e.g.: hidden!=true
​
fieldSelector
array
Field selector. e.g.: metadata.name==halo
​
sort
array
Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.
​
items
array
Array of user objects
​
page
integer
Current page number
​
size
integer
Size of each page
​
total
integer
Total number of users
​
totalPages
integer
Total number of pages

​
Create User

Create a new user account. 
curl -X POST "http://localhost:8091/apis/api.console.halo.run/v1alpha1/users" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "metadata": {
        "name": "johndoe"
      },
      "spec": {
        "displayName": "John Doe",
        "email": "[email protected]"
      }
    },
    "password": "securepassword123"
  }'
​
user
object
The created user object with metadata and spec

​
Get User Detail

Retrieve detailed information about a specific user. 
curl -X GET "http://localhost:8091/apis/api.console.halo.run/v1alpha1/users/{name}" \
  -H "Authorization: Bearer {token}"
​
name
string
required
User name/identifier
​
user
object
The user object
​
roles
array
Array of role names assigned to the user

​
Get Current User

Get details of the currently authenticated user. 
curl -X GET "http://localhost:8091/apis/api.console.halo.run/v1alpha1/users/-" \
  -H "Authorization: Bearer {token}"
​
user
object
Current user object
​
roles
array
Roles assigned to current user

​
Update Current User

Update the profile of the currently authenticated user (excluding password). 
curl -X PUT "http://localhost:8091/apis/api.console.halo.run/v1alpha1/users/-" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "johndoe"
    },
    "spec": {
      "displayName": "John Updated",
      "email": "[email protected]",
      "bio": "Software developer"
    }
  }'
​
user
object
The updated user object

​
User Status

​
Enable User

Enable a disabled user account. 
curl -X POST "http://localhost:8091/apis/console.api.security.halo.run/v1alpha1/users/{username}/enable" \
  -H "Authorization: Bearer {token}"
​
username
string
required
Username to enable
​
user
object
The enabled user object

​
Disable User

Disable a user account. 
curl -X POST "http://localhost:8091/apis/console.api.security.halo.run/v1alpha1/users/{username}/disable" \
  -H "Authorization: Bearer {token}"
​
username
string
required
Username to disable
​
user
object
The disabled user object

​
Password Management

​
Change Own Password

Change the password of the currently authenticated user. 
curl -X PUT "http://localhost:8091/apis/api.console.halo.run/v1alpha1/users/-/password" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "oldPassword": "currentpassword",
    "password": "newpassword123"
  }'
​
oldPassword
string
required
Current password for verification
​
password
string
required
New password (minimum 5 characters)

​
Change User Password (Admin)

Change the password of any user (admin only). 
curl -X PUT "http://localhost:8091/apis/api.console.halo.run/v1alpha1/users/{name}/password" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "newpassword123"
  }'
​
name
string
required
User name. If the name is equal to ’-’, it will change the password of current user.
​
password
string
required
New password (minimum 5 characters)

​
Avatar Management

​
Upload User Avatar

Upload an avatar image for a user. 
curl -X POST "http://localhost:8091/apis/api.console.halo.run/v1alpha1/users/{name}/avatar" \
  -H "Authorization: Bearer {token}" \
  -F "file=@/path/to/avatar.jpg"
​
name
string
required
User name
​
user
object
Updated user object with avatar URL

​
Delete User Avatar

Remove the avatar of a user. 
curl -X DELETE "http://localhost:8091/apis/api.console.halo.run/v1alpha1/users/{name}/avatar" \
  -H "Authorization: Bearer {token}"
​
name
string
required
User name
​
user
object
Updated user object without avatar

​
Permissions

​
Get User Permissions

Retrieve all permissions for a specific user. 
curl -X GET "http://localhost:8091/apis/api.console.halo.run/v1alpha1/users/{name}/permissions" \
  -H "Authorization: Bearer {token}"
​
name
string
required
User name
​
permissions
array
Array of permission objects
​
roles
array
Array of role names

​
Grant Permissions

Grant specific permissions to a user. 
curl -X POST "http://localhost:8091/apis/api.console.halo.run/v1alpha1/users/{name}/permissions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "roles": ["contributor", "editor"]
  }'
​
name
string
required
User name
​
roles
array
required
Array of role names to grant
​
user
object
Updated user object with new permissions

​
Email Verification

​
Send Email Verification Code

Send a verification code to the user’s email. 
curl -X POST "http://localhost:8091/apis/api.console.halo.run/v1alpha1/users/-/send-email-verification-code" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'
​
email
string
required
Email address to send verification code to

​
Verify Email

Verify user’s email address using the verification code. 
curl -X POST "http://localhost:8091/apis/api.console.halo.run/v1alpha1/users/-/verify-email" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456"
  }'
​
code
string
required
Verification code received via email

​
Authentication Providers

​
List Auth Providers

Retrieve all available authentication providers. 
curl -X GET "http://localhost:8091/apis/api.console.halo.run/v1alpha1/auth-providers" \
  -H "Authorization: Bearer {token}"
​
providers
array
Array of authentication provider objects

​
Enable Auth Provider

Enable a specific authentication provider. 
curl -X PUT "http://localhost:8091/apis/api.console.halo.run/v1alpha1/auth-providers/{name}/enable" \
  -H "Authorization: Bearer {token}"
​
name
string
required
Auth provider name
​
provider
object
The enabled auth provider

​
Disable Auth Provider

Disable a specific authentication provider. 
curl -X PUT "http://localhost:8091/apis/api.console.halo.run/v1alpha1/auth-providers/{name}/disable" \
  -H "Authorization: Bearer {token}"
​
name
string
required
Auth provider name
​
provider
object
The disabled auth provider

Build docs developers (and LLMs) love

Get started for freeTalk to us