Users API

Complete API reference for profile management and account-level user administration.

Authentication Required: All user APIs require the X-API-Key header.

/v1/users/me is for self-service profile access. /v1/user-management/* is for account management, and most of those endpoints require an account root user.

Standard Response Format

Users APIs use the standard API envelope:

{
  "success": true,
  "data": {},
  "timestamp": "2026-04-17T12:34:56Z"
}

Some mutation endpoints return a top-level message and omit data.

API Endpoints

Get My Profile

GET /v1/users/me

Response

{
  "success": true,
  "data": {
    "user_id": "usr-abc123def456789",
    "account_id": "acc-123456789",
    "email": "john@example.com",
    "username": "john.developer",
    "display_name": "John Developer",
    "role": "user",
    "status": "active",
    "is_root_user": true,
    "email_verified": true,
    "description": "Full-stack developer",
    "last_login": "2026-04-17T08:45:00Z",
    "created_at": "2026-04-10T09:30:00Z",
    "oauth_provider": null,
    "oauth_provider_id": null,
    "has_local_password": true,
    "avatar_url": null,
    "account": {
      "account_id": "acc-123456789",
      "email": "owner@example.com",
      "display_name": "ScaleBox Team",
      "description": "Primary account",
      "status": "active",
      "is_verified": true,
      "created_at": "2026-04-01T00:00:00Z"
    }
  },
  "timestamp": "2026-04-17T12:00:00Z"
}

Update My Profile

PUT /v1/users/me

Request body

Name	Type	Required	Description
display_name	string	No	Updated display name
description	string	No	Updated description
role	string	No	Root users only: update own role
status	string	No	Root users only: update own status

Response

{
  "success": true,
  "message": "Profile updated successfully",
  "timestamp": "2026-04-17T12:01:00Z"
}

List Users

GET /v1/user-management/users

Account root users only.

Query parameters

Name	Type	Required	Description
page	integer	No	Page number, default `1`
limit	integer	No	Page size, default `50` (alias: `page_size`)
offset	integer	No	Offset, default `0` (alias: `skip`)
status	string	No	Optional filter such as `enabled` or `disabled`

Response

{
  "success": true,
  "data": {
    "users": [
      {
        "user_id": "usr-abc123def456789",
        "email": "john@example.com",
        "username": "john.developer",
        "display_name": "John Developer",
        "role": "user",
        "status": "active",
        "is_root_user": true,
        "email_verified": true,
        "created_at": "2026-04-10T09:30:00Z",
        "last_login": "2026-04-17T08:45:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "total_pages": 1
    }
  },
  "timestamp": "2026-04-17T12:02:00Z"
}

Create User

POST /v1/user-management/users

Account root users only.

Request body

Name	Type	Required	Description
email	string	Yes	User email
username	string	Yes	Username
display_name	string	No	Display name
role	string	Yes	User role
status	string	No	Initial status
description	string	No	Description

Response

{
  "success": true,
  "data": {
    "message": "User created successfully",
    "user": {
      "user_id": "usr-def456ghi789012",
      "email": "jane@example.com",
      "username": "jane.developer",
      "display_name": "Jane Developer",
      "role": "user",
      "status": "active",
      "is_root_user": false,
      "email_verified": false,
      "created_at": "2026-04-17T12:03:00Z"
    },
    "initial_password": "",
    "dedicated_signin_url": null
  },
  "timestamp": "2026-04-17T12:03:00Z"
}

Get User

GET /v1/user-management/users/{user_id}

Account root users only.

Response

{
  "success": true,
  "data": {
    "user_id": "usr-def456ghi789012",
    "email": "jane@example.com",
    "username": "jane.developer",
    "display_name": "Jane Developer",
    "role": "user",
    "status": "active",
    "is_root_user": false,
    "email_verified": false,
    "created_at": "2026-04-17T12:03:00Z",
    "last_login": null,
    "description": ""
  },
  "timestamp": "2026-04-17T12:04:00Z"
}

Update User

PUT /v1/user-management/users/{user_id}

Account root users only.

Request body

Name	Type	Required	Description
display_name	string	No	New display name
role	string	No	New role
status	string	No	New status
description	string	No	New description

Response

{
  "success": true,
  "message": "User updated successfully",
  "timestamp": "2026-04-17T12:05:00Z"
}

Delete User

DELETE /v1/user-management/users/{user_id}

Account root users only.

Response

{
  "success": true,
  "data": {
    "message": "User marked for deletion. Resource cleanup is running in the background.",
    "deleted_empty_projects": 2,
    "deletion_status": "in_progress",
    "note": "Harbor user deletion and Kubernetes cleanup will continue asynchronously."
  },
  "timestamp": "2026-04-17T12:06:00Z"
}

Reset User Password

POST /v1/user-management/users/{user_id}/reset-password

Account root users only.

Response

{
  "success": true,
  "data": {
    "message": "Password reset link has been sent to the user's email. The link will expire in 30 minutes."
  },
  "timestamp": "2026-04-17T12:07:00Z"
}

Change My Password

POST /v1/user-management/change-password

This in-place change flow is for accounts that already have a local password. Use the email reset flow instead when no local password exists yet or the current password is unavailable.

Request body

Name	Type	Required	Description
current_password	string	Yes	Current local password for verification in this authenticated direct-change flow
new_password	string	Yes	New password, minimum 8 characters, and it must differ from `current_password`

Response

{
  "success": true,
  "message": "Password changed successfully",
  "timestamp": "2026-04-17T12:08:00Z"
}

Request My Password Reset Email

POST /v1/user-management/request-password-reset

Send a password reset email to the currently authenticated user. Use this recovery path when the account does not have a local password yet or the current password is unavailable.

Response

{
  "success": true,
  "message": "Password reset link sent to your email",
  "timestamp": "2026-04-17T12:09:00Z"
}

Rate-limited requests can return 429 with an error plus data.time_remaining_minutes.

Common Errors

{
  "success": false,
  "error": "Only root users can list users",
  "timestamp": "2026-04-17T12:10:00Z"
}

Common user errors:

400: invalid request body, weak password, incorrect current password, or forbidden state transition
403: non-root caller used an account-management endpoint
404: target user not found in the current account
429: password reset requested too recently
500: persistence, email, or background cleanup failure

Users API

On this page