HubUserClient

Part of the Kipu Quantum Hub API SDK reference - see the landing page for installation and Python credential helpers.

HubUserClient talks to the user-service. Use it to read the currently-authenticated user's profile, manage personal access tokens, resolve user identities, and search the user directory.

Authentication

HubUserClient authenticates with a personal access token sent as the X-Auth-Token request header. The same Python credential helpers documented under Python credential helpers work here - pass the resolved token via api_key.

The users, user_registration_status, and authentication namespaces are public/registration-oriented and do not require an authenticated principal; the remaining namespaces operate on the current user and do.

Quickstart

Fetch the current user and list their personal access tokens.

from qhub.api.user import HubUserClient

user = HubUserClient(api_key="YOUR_PERSONAL_ACCESS_TOKEN")

me = user.user_settings.get_current_user()
tokens = user.user_settings_personal_access_tokens.get_personal_access_tokens()

print(me.email, [t.name for t in tokens.access_tokens or []])

Constructor

Parameter	Required	Description
api_key / apiKey	yes	Personal access token; sent as X-Auth-Token.
base_url / baseUrl	no	Overrides both the default environment and environment if supplied.
environment	no	HubUserClientEnvironment.DEFAULT (Python) / HubUserEnvironment.Default (TypeScript).
headers	no	Additional headers merged into every request.
timeout / timeoutInSeconds	no	Read timeout in seconds; defaults to 60 when no custom HTTP client is supplied.
max_retries / maxRetries	no	Number of retries for transient failures; defaults to 2.
follow_redirects	no (Python only)	Passed through to httpx.Client; defaults to True.
httpx_client / fetch	no	Inject a preconfigured HTTP client (Python) or fetch implementation (TypeScript).
logging	no	Logger instance or {level, logger, silent} config dict.

Python also ships AsyncHubUserClient with the same shape plus an httpx.AsyncClient hook.

Behaviour

• base_url / baseUrl always wins over environment; omitting both in Python raises Exception("Please pass in either base_url or environment to construct the client").
• check_user_exists is a HEAD existence check: it returns the response headers (Dict[str, str] in Python, a Headers object in TypeScript) when the user exists and raises NotFoundError (404) otherwise - treat a thrown NotFoundError, not a falsy return, as "does not exist".
• get_user_profile_image returns a nullable string (Optional[str] / string | undefined), not raw bytes; the value is absent when the user has no profile image.
• A personal access token's raw value is returned only once, at creation or default-token regeneration; subsequent reads omit it.

Namespaces

Namespace	Purpose
user_settings	Current-user profile: get, update, delete, manage profile image.
user_settings_personal_access_tokens	List, create, delete, and regenerate personal access tokens for the current user.
authentication	Resolve the principal for a personal access token.
users	Look up users by id, check existence, fetch profile images.
user_registration_status	Read the registration status of a user by email.
search	Search the user directory.

TypeScript exposes the same namespaces in camelCase (userSettings, userSettingsPersonalAccessTokens, authentication, users, userRegistrationStatus, search).

Current user profile

Operations on the currently-authenticated user, under the user_settings (Python) / userSettings (TypeScript) namespace.

Method	Description
user_settings.get_current_user()	Full profile of the current user.
user_settings.update_current_user(current_position=?, homepage=?, about=?)	Update editable profile fields.
user_settings.delete_current_user()	Permanently delete the current user.
user_settings.update_current_user_profile_image(file=...)	Upload or replace the profile image.
user_settings.delete_current_user_profile_image()	Delete the profile image.

get_current_user

Return the full profile of the currently-authenticated user. If the user does not yet exist in the user-service database, it is provisioned just-in-time from the identity provider and then returned.

This method takes no arguments beyond per-request options.

me = user.user_settings.get_current_user()
print(me.id, me.email, me.firstname, me.lastname)

Returns UserDto - see UserDto.

update_current_user

Update the editable profile fields. Core identity fields (email, first name, last name) are owned by the identity provider and cannot be changed here.

Parameter	Required	Type	Default	Description
current_position	no	str? / string?	—	Current professional position or role.
homepage	no	str? / string?	—	Personal or professional homepage (fully-qualified URL).
about	no	str? / string?	—	Short biography shown on the profile.

me = user.user_settings.update_current_user(
    current_position="Quantum Engineer",
    homepage="https://example.com",
    about="Working on variational algorithms.",
)

Returns UserDto with the updated values applied.

delete_current_user

Permanently delete the current user together with all associated resources (personal access tokens, profile image, profile metadata), and remove the user from the identity provider. The operation cannot be undone.

This method takes no arguments beyond per-request options.

user.user_settings.delete_current_user()

Responds with 204 No Content; no body is returned.

update_current_user_profile_image

Upload or replace the current user's profile image. The image is sent as a multipart form part named file.

Parameter	Required	Type	Default	Description
file	yes	core.File / core.file.Uploadable	—	The profile image to upload.

with open("avatar.png", "rb") as f:
    user.user_settings.update_current_user_profile_image(file=f)

Responds with 204 No Content; no body is returned.

delete_current_user_profile_image

Remove the current user's profile image. Idempotent - succeeds even when no image is set.

This method takes no arguments beyond per-request options.

user.user_settings.delete_current_user_profile_image()

Responds with 204 No Content; no body is returned.

Personal access tokens

Manage the current user's personal access tokens (PATs), under the user_settings_personal_access_tokens (Python) / userSettingsPersonalAccessTokens (TypeScript) namespace.

Method	Description
user_settings_personal_access_tokens.get_personal_access_tokens()	List all PATs plus the default token value.
user_settings_personal_access_tokens.create_personal_access_token(name=..., expires_at=?)	Create a new PAT; raw value returned once.
user_settings_personal_access_tokens.delete_personal_access_token(id)	Delete a PAT by id.
user_settings_personal_access_tokens.regenerate_default_personal_access_token()	Rotate the default PAT.

get_personal_access_tokens

List all personal access tokens for the current user, together with the raw value of the current default token. The raw value of individual tokens is omitted on reads.

This method takes no arguments beyond per-request options.

tokens = user.user_settings_personal_access_tokens.get_personal_access_tokens()
for token in tokens.access_tokens or []:
    print(token.id, token.name, token.expires_at)

Returns AccessTokensDto - see AccessTokensDto.

create_personal_access_token

Create a new personal access token. The raw value is returned exactly once, on this response; store it immediately.

Parameter	Required	Type	Default	Description
name	yes	str / string	—	Human-readable token name.
expires_at	no	str? / string?	—	Expiry date as yyyy-MM-dd; omit for no expiry.

token = user.user_settings_personal_access_tokens.create_personal_access_token(
    name="ci-token",
    expires_at="2027-01-01",
)
print(token.value)  # shown only here

Returns AccessTokenDto - see AccessTokenDto.

delete_personal_access_token

Permanently delete a personal access token by id. The token must belong to the calling user.

Parameter	Required	Type	Default	Description
id	yes	str / string	—	Id of the token to delete.

user.user_settings_personal_access_tokens.delete_personal_access_token(token_id)

Responds with 204 No Content; no body is returned.

regenerate_default_personal_access_token

Rotate the default personal access token and return its new raw value. The previous default value is invalidated.

This method takes no arguments beyond per-request options.

result = user.user_settings_personal_access_tokens.regenerate_default_personal_access_token()
print(result.default_token)  # shown only here

Returns DefaultAccessTokenDto - see DefaultAccessTokenDto.

Principal resolution

Resolve a personal access token into an authenticated principal, under the authentication namespace. This is an internal/gateway-oriented endpoint: it validates the PAT carried in the X-Auth-Token header and returns the resolved user.

authorize_by_personal_access_token

Validate the current token and return the authenticated principal (user id plus token metadata).

This method takes no arguments beyond per-request options.

principal = user.authentication.authorize_by_personal_access_token()
print(principal.id, principal.access_token.name if principal.access_token else None)

Returns PersonalAccessTokenPrincipal - see PersonalAccessTokenPrincipal.

User lookup

Public read access to user profiles and profile images, under the users namespace.

Method	Description
users.get_user_by_id(id)	Public overview of a user.
users.check_user_exists(id)	HEAD-style existence check.
users.get_user_profile_image(id)	Fetch a user's profile image.

get_user_by_id

Return a public overview (id, first name, last name) of a user.

Parameter	Required	Type	Default	Description
id	yes	str / string	—	User identifier.

overview = user.users.get_user_by_id(user_id)
print(overview.firstname, overview.lastname)

Returns UserOverviewDto - see UserOverviewDto.

check_user_exists

HEAD-style existence check for a user. Returns the response headers when the user exists and raises NotFoundError (404) otherwise - see Behaviour.

Parameter	Required	Type	Default	Description
id	yes	str / string	—	User identifier.

from qhub.api.user.errors import NotFoundError

try:
    user.users.check_user_exists(user_id)
    exists = True
except NotFoundError:
    exists = False

Returns the response headers (Dict[str, str] / Headers); no body is emitted.

get_user_profile_image

Fetch a user's profile image. Returns None / undefined when the user has no image; raises NotFoundError (404) when the user does not exist.

Parameter	Required	Type	Default	Description
id	yes	str / string	—	User identifier.

image = user.users.get_user_profile_image(user_id)

Returns Optional[str] / string | undefined - see Behaviour for the nullable-string contract.

User registration status

Read the registration state of a user identified by email, under the user_registration_status (Python) / userRegistrationStatus (TypeScript) namespace.

get_user_registration_status

Return the registration status for an email address; drives the registration flow.

Parameter	Required	Type	Default	Description
email	yes	str / string	—	Email address to query (sent as a query parameter).

status = user.user_registration_status.get_user_registration_status(
    email="someone@example.com",
)
print(status.status, status.message)

Returns RegistrationResponse - see RegistrationResponse.

User search

Full-text search across user profiles, under the search namespace.

users

Case-insensitive substring search over first name, last name, username, and email.

Parameter	Required	Type	Default	Description
q	yes	str / string	—	Search query (sent as a query parameter).

results = user.search.users(q="alice")
for match in results:
    print(match.id, match.firstname, match.lastname)

Returns a plain (possibly empty) List[UserSearchDto] / UserSearchDto[] - there is no pagination wrapper. See UserSearchDto.

Endpoints

Default base URL	Override
https://api.hub.kipu-quantum.com/user-service	base_url=... / baseUrl: ..., or environment=HubUserClientEnvironment.DEFAULT (Python) / environment: HubUserEnvironment.Default (TypeScript).

Errors

All Python errors extend ApiError (in qhub.api.user.core.api_error); all TypeScript errors extend HubUserError.

Status	Python class	TypeScript class	Meaning
400	BadRequestError	BadRequestError	Malformed request.
401	UnauthorizedError	UnauthorizedError	Missing or invalid credentials.
403	ForbiddenError	ForbiddenError	Authenticated but not permitted.
404	NotFoundError	NotFoundError	Resource does not exist.

Other failure modes:

• Auth misconfiguration (TypeScript) - constructing HubUserClient without apiKey throws HubUserError with message "Please provide 'apiKey' when initializing the client".
• Timeouts - hitting timeoutInSeconds raises HubUserTimeoutError in TypeScript; in Python, timeouts surface as the underlying httpx.TimeoutException.

All HTTP error instances expose status_code, headers, and body (Python) / statusCode, rawResponse, and body (TypeScript).

Reference

UserDto

Full profile of the currently-authenticated user.

Field	Python / wire name	Type	Description
id	id	str?	Unique id (identity-provider subject).
username	username	str?	Login name (typically the email).
email	email	str?	Email address (identity-provider managed).
firstname	firstname	str?	First (given) name.
lastname	lastname	str?	Last (family) name.
current_position	current_position / currentPosition	str?	Current professional position or role.
homepage	homepage	str?	Personal or professional homepage.
about	about	str?	Short biography.

AccessTokenDto

A personal access token belonging to a user.

Field	Python / wire name	Type	Description
id	id	str?	Unique id of the token.
name	name	str	Human-readable token name.
created_at	created_at / createdAt	str?	Creation timestamp (yyyy-MM-dd HH:mm:ss, UTC).
used_at	used_at / usedAt	str?	Last-used timestamp; null if never used.
expires_at	expires_at / expiresAt	str?	Expiry (yyyy-MM-dd); null means never expires.
value	value	str?	Raw token value; returned only once at creation, null on reads.

AccessTokensDto

Container for a user's personal access tokens plus the raw default-token value.

Field	Python / wire name	Type	Description
default_token	default_token / defaultToken	str?	Raw value of the current default PAT.
access_tokens	access_tokens / accessTokens	List[AccessTokenDto]?	All PATs for the user; may be empty.

DefaultAccessTokenDto

Response wrapping a newly-generated default personal access token value.

Field	Python / wire name	Type	Description
default_token	default_token / defaultToken	str?	Raw value of the regenerated default PAT (returned once).

PersonalAccessTokenPrincipal

Authenticated principal resolved from a personal access token.

Field	Python / wire name	Type	Description
id	id	str?	Unique id of the authenticated user.
access_token	access_token / accessToken	AccessTokenDto?	Metadata of the PAT used to authenticate; raw value never included.

RegistrationResponse

Registration status of a user, used by the registration flow.

Field	Python / wire name	Type	Description
status	status	RegistrationResponseStatus?	Current registration status (see Enums).
message	message	str?	Human-readable message for the status.

UserOverviewDto

Minimal public representation of a user.

Field	Python / wire name	Type	Description
id	id	str?	Unique id.
firstname	firstname	str?	First (given) name.
lastname	lastname	str?	Last (family) name.

UserSearchDto

Entry in the user-search result list (returned as a bare array).

Field	Python / wire name	Type	Description
id	id	str?	Unique id of the match.
firstname	firstname	str?	First (given) name.
lastname	lastname	str?	Last (family) name.

Enums

• RegistrationResponseStatus - PENDING | APPROVED | REJECTED | NOT_FOUND | EMAIL_NOT_VERIFIED

Field casing

User-API DTOs use snake_case in Python and camelCase in TypeScript. Single-word fields (id, email, firstname, lastname, username, name, value, homepage, about, status, message) are identical across both; the aliased fields are currentPosition, createdAt, usedAt, expiresAt, defaultToken, accessTokens, and accessToken.