Users API

API for user management.

Overview

Through the Users API, you can create, retrieve, update, and delete D.Hub users. This API requires administrator privileges.

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

For security, the password_hash field is excluded from the response.

---

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 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	Belonging 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 updated.

{
  "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	Belonging 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	List of belonging groups
tags	array	List of tags
provider	string	Authentication provider (local, ldap, oidc)
is_active	boolean	Active status
roles	array	List of roles
created_at	string	Creation time
updated_at	string	Modification time

Usage Examples

cURL

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

# Create 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 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 user
curl -X DELETE https://api.dhub.io/api/v1/users/user-abc123 \
  -H "Authorization: Bearer <access_token>"