Users API

API for user management.

Overview

The Users API allows you to create, retrieve, update, and delete D.Hub users. Admin privileges are required.

Endpoints

GET /api/v1/users/

Retrieves a list of all users.

Query Parameters

Parameter	Type	Default	Description
limit	integer	100	Maximum number of items to retrieve
token	string	-	Pagination token

Response

200 OK

{
  "items": {
    "user-abc123": "{\"id\":\"user-abc123\",\"email\":\"user@example.com\",...}",
    "user-xyz789": "{\"id\":\"user-xyz789\",\"email\":\"admin@example.com\",...}"
  },
  "token": "next-page-token"
}

note

The password_hash field is excluded from responses for security.

---

GET /api/v1/users/{user_id}/versions

Retrieves the version history of a user.

Path Parameters

Parameter	Type	Required	Description
user_id	string	Yes	User ID

Response

200 OK

[
  {
    "version_id": "v2",
    "last_modified": "2024-01-20T10:30:00Z",
    "size": 512
  }
]

---

GET /api/v1/users/{user_id}

Retrieves a specific user.

Path Parameters

Parameter	Type	Required	Description
user_id	string	Yes	User ID

Query Parameters

Parameter	Type	Required	Description
user_version	string	No	Retrieve a specific version

Response

200 OK

{
  "id": "user-abc123",
  "email": "user@example.com",
  "name": "John Doe",
  "alias": "john",
  "type": "user",
  "groups": ["developers"],
  "tags": [],
  "provider": "local",
  "is_active": true,
  "roles": ["user"],
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-15T09:00:00Z"
}

Error Responses

Status Code	Description
404 Not Found	User not found

---

POST /api/v1/users/

Creates a new user.

Request Body

{
  "email": "newuser@example.com",
  "name": "New User",
  "password": "secure-password",
  "groups": ["developers"],
  "tags": []
}

Field	Type	Required	Description
email	string	Yes	Email (unique)
name	string	Yes	User name
password	string	Yes	Password
alias	string	No	Alias
groups	array	No	Affiliated groups
tags	array	No	Tags

Response

200 OK

{
  "item": "user-newid123"
}

Error Responses

Status Code	Description
409 Conflict	Email already exists

---

PUT /api/v1/users/{user_id}

Updates user information.

Path Parameters

Parameter	Type	Required	Description
user_id	string	Yes	User ID

Request Body

Include only the fields to be modified.

{
  "name": "Updated Name",
  "email": "newemail@example.com",
  "groups": ["developers", "admins"]
}

Field	Type	Description
name	string	User name
alias	string	Alias
type	string	User type
email	string	Email (duplicate check on change)
groups	array	Affiliated groups
tags	array	Tags
comment	string	Modification comment

Response

200 OK

{
  "message": "User updated successfully"
}

Error Responses

Status Code	Description
404 Not Found	User not found
409 Conflict	Email already exists

---

DELETE /api/v1/users/{user_id}

Deletes a user.

Path Parameters

Parameter	Type	Required	Description
user_id	string	Yes	User ID

Response

200 OK

{
  "message": "User deleted successfully"
}

Error Responses

Status Code	Description
404 Not Found	User not found

User Object

Field	Type	Description
id	string	User unique ID
email	string	Email address
name	string	User name
alias	string	Alias
type	string	User type (user, admin, etc.)
groups	array	Affiliated group list
tags	array	Tag list
provider	string	Auth provider (local, ldap, oidc)
is_active	boolean	Active status
roles	array	Role list
created_at	string	Creation time
updated_at	string	Update time

Usage Examples

cURL

# List users
curl https://api.dhub.io/api/v1/users/ \
  -H "Authorization: Bearer <access_token>"

# Create a user
curl -X POST https://api.dhub.io/api/v1/users/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "name": "New User",
    "password": "secure-password"
  }'

# Update a user
curl -X PUT https://api.dhub.io/api/v1/users/user-abc123 \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name"}'

# Delete a user
curl -X DELETE https://api.dhub.io/api/v1/users/user-abc123 \
  -H "Authorization: Bearer <access_token>"