API Reference

HMAC signing

Open APIs no longer accept an API Secret header. Use the Secret returned once at client creation to compute HMAC-SHA256 and send it as X-Signature.

Header

Field	In	Type	Example	Description
`X-Tenant-ID`Required	Header	uuid	`3a1c0e22-8f14-4b9d-91aa-0c2d6e8f4b11`	Tenant ID; must be a valid UUID
`X-App-ID`Required	Header	string	`app_aaff3723c31a6c19`	Application ID delivered after approval
`X-API-Key`Required	Header	string	`8432ebe0e0bba82ecf64d54288349b7c`	API Key delivered after approval
`X-Timestamp`Required	Header	int64	`1756107600`	Unix timestamp in seconds; 5-minute clock skew allowed by default
`X-Nonce`Required	Header	string	`n7Kq2mR9xL4pQw8Z`	16–128 character URL-safe nonce (A-Za-z0-9_-), unique per request
`X-Signature`Required	Header	string	`a1b2c3d4e5f6...`	HMAC-SHA256 of the canonical request, lowercase hex

Canonical request

Join the following fields in order with a newline. Keep the empty line even when the query string is empty:

canonical

HTTP_METHOD_UPPERCASE
ESCAPED_PATH
SORTED_QUERY_STRING
TENANT_ID
APP_ID
API_KEY
UNIX_TIMESTAMP
NONCE
LOWERCASE_HEX_SHA256_BODY

The HMAC key is the 32-byte SHA256(API_SECRET) digest, not the plaintext secret. Timestamps allow a 5-minute skew by default, and each nonce can be used only once. Long-term integrations should migrate to OAuth 2.0 client credentials.

Signing example

Node.js

const crypto = require('crypto')

function sign({ method, path, query, tenantId, appId, apiKey, secret, timestamp, nonce, body }) {
  const bodyHash = crypto.createHash('sha256').update(body || '').digest('hex')
  const canonical = [
    method.toUpperCase(),
    path,
    query,
    tenantId,
    appId,
    apiKey,
    String(timestamp),
    nonce,
    bodyHash,
  ].join('\n')
  const key = crypto.createHash('sha256').update(secret).digest()
  return crypto.createHmac('sha256', key).update(canonical).digest('hex')
}

Integration requests (public, no authentication required)

POST/api/v1/access-requestsNo auth

Submit an API access request

Publicly submit an access request. A pending request for the same email returns 409; success returns 201. The review result is emailed.

Field	In	Type	Example	Description
`applicant_name`Required	Body	string	`Jane Doe`	Applicant name, max 100 characters
`email`Required	Body	string	`dev@example.com`	Contact email, max 254 characters; only one pending request is allowed per email
`company`	Body	string	`Example Tech`	Company / organization, max 200 characters
`project_name`Required	Body	string	`Internal OA`	Project name, max 200 characters
`purpose`Required	Body	string	`Sync identity and check application access`	Intended use, max 2000 characters

Field	In	Type	Example	Description
`id`Required	Response	uuid	`7c2f1a90-4d3b-4e8a-9c11-2b0f6d8a1e44`	Request ID
`applicant_name`Required	Response	string	`Jane Doe`	Applicant name
`email`Required	Response	string	`dev@example.com`	Contact email
`company`	Response	string	`Example Tech`	Company / organization
`project_name`Required	Response	string	`Internal OA`	Integration project name
`purpose`Required	Response	string	`Sync identity and check application access`	Integration use case
`status`Required	Response	string	`pending`	Review status; pending after submit
`review_note`	Response	string		Review note; empty on submit
`reviewed_by`	Response	uuid \| null	`null`	Reviewer ID; omitted or empty on submit
`reviewed_at`	Response	datetime \| null	`null`	Reviewed at; empty on submit
`created_at`Required	Response	datetime	`2026-08-25T14:20:00+08:00`	Created at (ISO 8601 with time zone)
`updated_at`Required	Response	datetime	`2026-08-25T14:20:00+08:00`	Updated at (ISO 8601 with time zone)

Authentication and current user (JWT)

POST/api/v1/auth/register/send-codeNo auth

Send registration email code

Sends a 6-digit email code. The same mailbox is rate-limited to once per 60 seconds, and the code expires in 10 minutes. Call this before register.

Field	In	Type	Example	Description
`email`Required	Body	string	`test@example.com`	Mailbox that receives the code; format and domain deliverability are checked

Field	In	Type	Example	Description
`message`Required	Response	string	`Verification code sent`	Send result message

POST/api/v1/auth/registerNo auth

Register a new user

Register with an email code. username is 3–50 characters, password is at least 6 characters, email_code must be the 6-digit code just sent, and agree_terms must be true. Success returns 201.

Field	In	Type	Example	Description
`username`Required	Body	string	`testuser`	Username, 3–50 characters
`email`Required	Body	string	`test@example.com`	Email; must match the mailbox that received the code
`password`Required	Body	string	`Test@123456`	Password, at least 6 characters
`email_code`Required	Body	string	`123456`	6-digit email verification code
`agree_terms`Required	Body	boolean	`true`	Must be true to accept the terms and privacy policy

Field	In	Type	Example	Description
`id`Required	Response	uuid	`199ce8d6-788c-41cd-b3d9-b87abe8f35fa`	User ID
`username`Required	Response	string	`admin`	Username
`email`Required	Response	string	`admin@auth-one.local`	Email
`status`Required	Response	string	`active`	Account status, such as active / inactive
`roles`	Response	object[] \| null	`[{...}]`	Roles; null when none are assigned
`id`Required	Response	uuid	`b826ef2c-62ac-4ad9-aefa-02c6d0048d4f`	Role ID
`code`Required	Response	string	`admin`	Role code
`name`Required	Response	string	`admin`	Role name
`departments`	Response	object[] \| null	`[{...}]`	Departments; null when none are assigned
`id`Required	Response	uuid	`df2d69ab-56a9-43bf-8999-d60995719001`	Department ID
`code`Required	Response	string	`HQ`	Department code
`name`Required	Response	string	`HQ`	Department name
`positions`	Response	object[] \| null	`[{...}]`	Positions; null when none are assigned
`id`Required	Response	uuid	`e0f37812-21fb-47df-ad35-417fd4badff1`	Position ID
`name`Required	Response	string	`Admin`	Position name
`hash`Required	Response	string	`cfe7e40f3bbc7be47aea69b5803f366a...`	Integrity hash of the user record
`created_at`Required	Response	datetime	`2026-08-13T09:27:29+08:00`	Created at (ISO 8601 with time zone)
`updated_at`Required	Response	datetime	`2026-08-13T09:27:29+08:00`	Updated at (ISO 8601 with time zone)

POST/api/v1/auth/loginNo auth

Sign in a user and obtain an access token

username accepts a username or email. If the tenant requires MFA, the response may only include mfa_ticket until the challenge is completed.

Field	In	Type	Example	Description
`username`Required	Body	string	`admin`	Username or email
`password`Required	Body	string	`Admin@123456`	Password

Field	In	Type	Example	Description
`token`	Response	string	`eyJhbGciOiJIUzI1NiIs...`	Access token; omitted until MFA is completed
`refresh_token`	Response	string	`dGhpcy1pcy1hLXJlZnJl...`	Refresh token; may be omitted from the JSON body in cookie mode
`expires_at`	Response	datetime	`2026-08-26T14:20:00+08:00`	Access token expiry
`user`	Response	object	`{...}`	Current user object; nested fields are listed below
`id`Required	Response	uuid	`199ce8d6-788c-41cd-b3d9-b87abe8f35fa`	User ID
`username`Required	Response	string	`admin`	Username
`email`Required	Response	string	`admin@auth-one.local`	Email
`status`Required	Response	string	`active`	Account status, such as active / inactive
`roles`	Response	object[] \| null	`[{...}]`	Roles; null when none are assigned
`id`Required	Response	uuid	`b826ef2c-62ac-4ad9-aefa-02c6d0048d4f`	Role ID
`code`Required	Response	string	`admin`	Role code
`name`Required	Response	string	`admin`	Role name
`departments`	Response	object[] \| null	`[{...}]`	Departments; null when none are assigned
`id`Required	Response	uuid	`df2d69ab-56a9-43bf-8999-d60995719001`	Department ID
`code`Required	Response	string	`HQ`	Department code
`name`Required	Response	string	`HQ`	Department name
`positions`	Response	object[] \| null	`[{...}]`	Positions; null when none are assigned
`id`Required	Response	uuid	`e0f37812-21fb-47df-ad35-417fd4badff1`	Position ID
`name`Required	Response	string	`Admin`	Position name
`hash`Required	Response	string	`cfe7e40f3bbc7be47aea69b5803f366a...`	Integrity hash of the user record
`created_at`Required	Response	datetime	`2026-08-13T09:27:29+08:00`	Created at (ISO 8601 with time zone)
`updated_at`Required	Response	datetime	`2026-08-13T09:27:29+08:00`	Updated at (ISO 8601 with time zone)
`mfa_required`	Response	boolean	`true`	When true, complete the MFA challenge with mfa_ticket
`mfa_ticket`	Response	string	`mfa_ticket_...`	One-time MFA ticket
`mfa_enrollment_required`	Response	boolean	`true`	True when the tenant requires MFA and the account has not enrolled
`email_code_required`	Response	boolean	`true`	True when a native client must complete the email-code second step
`email_code_ticket`	Response	string	`email_ticket_...`	One-time ticket for the native-client email-code second step

Response example

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "dGhpcy1pcy1hLXJlZnJlc2gtdG9rZW4...",
  "expires_at": "2026-08-26T14:20:00+08:00",
  "user": {
  "id": "199ce8d6-788c-41cd-b3d9-b87abe8f35fa",
  "username": "admin",
  "email": "admin@auth-one.local",
  "status": "active",
  "roles": [{ "id": "b826ef2c-62ac-4ad9-aefa-02c6d0048d4f", "code": "admin", "name": "admin" }],
  "departments": [{ "id": "df2d69ab-56a9-43bf-8999-d60995719001", "code": "HQ", "name": "HQ" }],
  "positions": [{ "id": "e0f37812-21fb-47df-ad35-417fd4badff1", "name": "Admin" }],
  "hash": "cfe7e40f3bbc7be47aea69b5803f366acb21a5a87f588826f3173fede3932122",
  "created_at": "2026-08-13T09:27:29+08:00",
  "updated_at": "2026-08-13T09:27:29+08:00"
}
}

GET/api/v1/users/meJWT Bearer

Get the current user

Returns the user object for the current JWT. The shape matches the user field from a successful login.

Field	In	Type	Example	Description
`Authorization`Required	Header	string	`Bearer eyJhbGciOiJIUzI1NiIs...`	Bearer access token

Field	In	Type	Example	Description
`id`Required	Response	uuid	`199ce8d6-788c-41cd-b3d9-b87abe8f35fa`	User ID
`username`Required	Response	string	`admin`	Username
`email`Required	Response	string	`admin@auth-one.local`	Email
`status`Required	Response	string	`active`	Account status, such as active / inactive
`roles`	Response	object[] \| null	`[{...}]`	Roles; null when none are assigned
`id`Required	Response	uuid	`b826ef2c-62ac-4ad9-aefa-02c6d0048d4f`	Role ID
`code`Required	Response	string	`admin`	Role code
`name`Required	Response	string	`admin`	Role name
`departments`	Response	object[] \| null	`[{...}]`	Departments; null when none are assigned
`id`Required	Response	uuid	`df2d69ab-56a9-43bf-8999-d60995719001`	Department ID
`code`Required	Response	string	`HQ`	Department code
`name`Required	Response	string	`HQ`	Department name
`positions`	Response	object[] \| null	`[{...}]`	Positions; null when none are assigned
`id`Required	Response	uuid	`e0f37812-21fb-47df-ad35-417fd4badff1`	Position ID
`name`Required	Response	string	`Admin`	Position name
`hash`Required	Response	string	`cfe7e40f3bbc7be47aea69b5803f366a...`	Integrity hash of the user record
`created_at`Required	Response	datetime	`2026-08-13T09:27:29+08:00`	Created at (ISO 8601 with time zone)
`updated_at`Required	Response	datetime	`2026-08-13T09:27:29+08:00`	Updated at (ISO 8601 with time zone)

PUT/api/v1/users/meJWT Bearer

Update current user information

Direct updates to username, email, roles, departments, or positions are rejected. Those identity attributes require a verified workflow. This endpoint always returns 405.

Field	In	Type	Example	Description
`Authorization`Required	Header	string	`Bearer eyJhbGciOiJIUzI1NiIs...`	Bearer access token
`email`	Body	string	`new@example.com`	Ignored; the endpoint rejects identity-field changes

Field	In	Type	Example	Description
`code`Required	Response	string	`PROFILE_IDENTITY_UPDATE_REQUIRES_VERIFICATION`	Business error code
`error`Required	Response	string	`Identity attributes can only be changed through a verified workflow`	Error message

PUT/api/v1/users/me/passwordJWT Bearer

Change the current user's password

Verifies the old password and sets a new one (at least 6 characters). Existing sessions may be revoked after success.

Field	In	Type	Example	Description
`Authorization`Required	Header	string	`Bearer eyJhbGciOiJIUzI1NiIs...`	Bearer access token
`old_password`Required	Body	string	`OldPass@123456`	Current password
`new_password`Required	Body	string	`NewPass@123456`	New password, at least 6 characters

Field	In	Type	Example	Description
`message`Required	Response	string	`Password changed successfully`	Change result message

Application and client management

GET/api/v1/applicationsJWT Bearer

List applications

Lists applications in the current tenant. Requires JWT. page starts at 1; page_size defaults to 20.

Field	In	Type	Example	Description
`Authorization`Required	Header	string	`Bearer eyJhbGciOiJIUzI1NiIs...`	Bearer access token
`page`	Query	int	`1`	Page number, starting at 1; default 1
`page_size`	Query	int	`20`	Page size; default 20, maximum 100

Field	In	Type	Example	Description
`data`Required	Response	object[]	`[{...}]`	Application objects
`id`Required	Response	uuid	`3a1c0e22-8f14-4b9d-91aa-0c2d6e8f4b11`	Application ID
`name`Required	Response	string	`Internal OA`	Application name
`code`Required	Response	string	`oa`	Application code
`description`	Response	string	`Internal portal`	Application description
`callback_url`	Response	string	`https://oa.example.com/callback`	Callback URL
`status`Required	Response	int16	`1`	Application status; 1 means enabled
`hash`Required	Response	string	`9a2f...`	Integrity hash of the application record
`tenant_id`Required	Response	uuid	`3a1c0e22-8f14-4b9d-91aa-0c2d6e8f4b11`	Tenant ID
`created_at`Required	Response	datetime	`2026-08-13T09:27:29+08:00`	Created at (ISO 8601 with time zone)
`updated_at`Required	Response	datetime	`2026-08-13T09:27:29+08:00`	Updated at (ISO 8601 with time zone)
`total`Required	Response	int	`1`	Total matching rows
`page`Required	Response	int	`1`	Current page
`page_size`Required	Response	int	`20`	Current page size

POST/api/v1/api-clientsJWT Bearer

Create API client (Secret is returned only once)

Creates an open-API client. api_secret is returned in plaintext only in this response, then stored as a hash. allow_ips is the caller IP/CIDR allowlist.

Field	In	Type	Example	Description
`Authorization`Required	Header	string	`Bearer eyJhbGciOiJIUzI1NiIs...`	Bearer access token
`app_name`Required	Body	string	`OA Integration`	Client display name
`contact_name`Required	Body	string	`Jane Doe`	Contact name
`contact_phone`Required	Body	string	`13800000000`	Contact phone
`contact_email`	Body	string	`dev@example.com`	Contact email
`apply_application_id`	Body	uuid	`3a1c0e22-8f14-4b9d-91aa-0c2d6e8f4b11`	Related application ID
`allow_ips`	Body	string[]	`["10.0.0.0/8"]`	Allowed caller IPs or CIDRs; open APIs enforce this list

Field	In	Type	Example	Description
`id`Required	Response	uuid	`c0a1b2d3-4e5f-6789-abcd-ef0123456789`	Client record ID
`app_id`Required	Response	string	`app_aaff3723c31a6c19`	App ID used when calling open APIs
`app_name`Required	Response	string	`OA Integration`	Client display name
`api_key`Required	Response	string	`8432ebe0e0bba82ecf64d54288349b7c`	API Key
`api_secret`Required	Response	string	`d3cef27cf11fe8f5...`	Plaintext secret, returned only once; later used locally to compute HMAC
`contact_name`Required	Response	string	`Jane Doe`	Contact name
`contact_phone`Required	Response	string	`13800000000`	Contact phone
`contact_email`	Response	string	`dev@example.com`	Contact email
`status`Required	Response	int16	`1`	Client status; 1 means enabled
`created_at`Required	Response	datetime	`2026-08-25T14:20:00+08:00`	Created at (ISO 8601 with time zone)
`message`Required	Response	string	`Please save the api_secret securely...`	Reminder to save the secret immediately

POST/api/v1/api-clients/{id}/regenerate-secretJWT Bearer

Regenerate client secret

Invalidates the old secret and returns a new plaintext secret, also shown only once. Later signatures must use the new secret.

Field	In	Type	Example	Description
`Authorization`Required	Header	string	`Bearer eyJhbGciOiJIUzI1NiIs...`	Bearer access token
`id`Required	Path	uuid	`c0a1b2d3-4e5f-6789-abcd-ef0123456789`	Client record ID

Field	In	Type	Example	Description
`api_secret`Required	Response	string	`9f1e2d3c4b5a6978...`	New plaintext secret, returned only once
`message`Required	Response	string	`Please save the new api_secret securely...`	Reminder to save the secret immediately

POST/api/v1/api-clients/validateJWT Bearer

Validate client credentials

Validates a client with App ID / API Key / Secret. Use this only for local testing. Production open APIs must use HMAC and must not send the plaintext secret.

Field	In	Type	Example	Description
`Authorization`Required	Header	string	`Bearer eyJhbGciOiJIUzI1NiIs...`	Bearer access token
`app_id`Required	Body	string	`app_aaff3723c31a6c19`	Client App ID
`api_key`Required	Body	string	`8432ebe0e0bba82ecf64d54288349b7c`	API Key
`api_secret`Required	Body	string	`d3cef27cf11fe8f5...`	Plaintext secret from create or regenerate

Field	In	Type	Example	Description
`valid`Required	Response	boolean	`true`	Whether the credentials are valid
`app_id`	Response	string	`app_aaff3723c31a6c19`	App ID returned when validation succeeds
`app_name`	Response	string	`OA Integration`	Client name returned when validation succeeds
`error`	Response	string	`invalid credentials`	Error message when validation fails; valid is false

Open APIs (HMAC signature authentication)

GET/api/v1/external/users/{id}HMAC signing

Get basic user information

Read basic profile by user ID. Open APIs are disabled by default, require HTTPS in production, and the caller IP must be on the client allowlist.

Field	In	Type	Example	Description
`id`Required	Path	uuid	`199ce8d6-788c-41cd-b3d9-b87abe8f35fa`	User ID
`X-Tenant-ID`Required	Header	uuid	`3a1c0e22-8f14-4b9d-91aa-0c2d6e8f4b11`	Tenant ID; must be a valid UUID
`X-App-ID`Required	Header	string	`app_aaff3723c31a6c19`	Application ID delivered after approval
`X-API-Key`Required	Header	string	`8432ebe0e0bba82ecf64d54288349b7c`	API Key delivered after approval
`X-Timestamp`Required	Header	int64	`1756107600`	Unix timestamp in seconds; 5-minute clock skew allowed by default
`X-Nonce`Required	Header	string	`n7Kq2mR9xL4pQw8Z`	16–128 character URL-safe nonce (A-Za-z0-9_-), unique per request
`X-Signature`Required	Header	string	`a1b2c3d4e5f6...`	HMAC-SHA256 of the canonical request, lowercase hex

Field	In	Type	Example	Description
`id`Required	Response	uuid	`199ce8d6-788c-41cd-b3d9-b87abe8f35fa`	User ID
`username`Required	Response	string	`admin`	Username
`email`Required	Response	string	`admin@auth-one.local`	Email
`status`Required	Response	string	`active`	Account status, such as active / inactive
`roles`	Response	object[] \| null	`[{...}]`	Roles; null when none are assigned
`id`Required	Response	uuid	`b826ef2c-62ac-4ad9-aefa-02c6d0048d4f`	Role ID
`code`Required	Response	string	`admin`	Role code
`name`Required	Response	string	`admin`	Role name
`departments`	Response	object[] \| null	`[{...}]`	Departments; null when none are assigned
`id`Required	Response	uuid	`df2d69ab-56a9-43bf-8999-d60995719001`	Department ID
`code`Required	Response	string	`HQ`	Department code
`name`Required	Response	string	`HQ`	Department name
`positions`	Response	object[] \| null	`[{...}]`	Positions; null when none are assigned
`id`Required	Response	uuid	`e0f37812-21fb-47df-ad35-417fd4badff1`	Position ID
`name`Required	Response	string	`Admin`	Position name
`hash`Required	Response	string	`cfe7e40f3bbc7be47aea69b5803f366a...`	Integrity hash of the user record
`created_at`Required	Response	datetime	`2026-08-13T09:27:29+08:00`	Created at (ISO 8601 with time zone)
`updated_at`Required	Response	datetime	`2026-08-13T09:27:29+08:00`	Updated at (ISO 8601 with time zone)

POST/api/v1/external/users/check-accessHMAC signing

Check whether a user can access an application

Checks whether the user has a valid grant for the application. has_access is false when there is no grant; authorization may be null.

Field	In	Type	Example	Description
`user_id`Required	Body	uuid	`199ce8d6-788c-41cd-b3d9-b87abe8f35fa`	User ID
`application_id`Required	Body	uuid	`3a1c0e22-8f14-4b9d-91aa-0c2d6e8f4b11`	Application ID
`X-Tenant-ID`Required	Header	uuid	`3a1c0e22-8f14-4b9d-91aa-0c2d6e8f4b11`	Tenant ID; must be a valid UUID
`X-App-ID`Required	Header	string	`app_aaff3723c31a6c19`	Application ID delivered after approval
`X-API-Key`Required	Header	string	`8432ebe0e0bba82ecf64d54288349b7c`	API Key delivered after approval
`X-Timestamp`Required	Header	int64	`1756107600`	Unix timestamp in seconds; 5-minute clock skew allowed by default
`X-Nonce`Required	Header	string	`n7Kq2mR9xL4pQw8Z`	16–128 character URL-safe nonce (A-Za-z0-9_-), unique per request
`X-Signature`Required	Header	string	`a1b2c3d4e5f6...`	HMAC-SHA256 of the canonical request, lowercase hex

Field	In	Type	Example	Description
`has_access`Required	Response	boolean	`true`	Whether the user currently has access
`authorization`	Response	object \| null	`{...}`	Grant record; null when missing. Access is valid only when status is 1 and it has not expired
`id`Required	Response	uuid	`9d4e2c18-71aa-4f03-8b55-1e6c0a9d2f70`	Grant ID
`user_id`Required	Response	uuid	`199ce8d6-788c-41cd-b3d9-b87abe8f35fa`	User ID
`application_id`Required	Response	uuid	`3a1c0e22-8f14-4b9d-91aa-0c2d6e8f4b11`	Application ID
`scopes`	Response	object \| null	`null`	Scopes; null when unset
`expires_at`	Response	datetime \| null	`null`	Grant expiry; empty means it does not expire
`status`Required	Response	int16	`1`	Grant status; 1 means active
`hash`Required	Response	string	`8b1c...`	Integrity hash of the grant record
`created_at`Required	Response	datetime	`2026-08-13T09:27:29+08:00`	Created at (ISO 8601 with time zone)
`updated_at`Required	Response	datetime	`2026-08-13T09:27:29+08:00`	Updated at (ISO 8601 with time zone)

POST/api/v1/external/third-party/find-userHMAC signing

Find a user by third-party account

Find a bound Auth-One user by third-party provider and user ID. Returns 404 when not found.

Field	In	Type	Example	Description
`provider`Required	Body	string	`github`	Third-party provider id, such as github / wechat
`provider_user_id`Required	Body	string	`123456`	User ID on that provider
`X-Tenant-ID`Required	Header	uuid	`3a1c0e22-8f14-4b9d-91aa-0c2d6e8f4b11`	Tenant ID; must be a valid UUID
`X-App-ID`Required	Header	string	`app_aaff3723c31a6c19`	Application ID delivered after approval
`X-API-Key`Required	Header	string	`8432ebe0e0bba82ecf64d54288349b7c`	API Key delivered after approval
`X-Timestamp`Required	Header	int64	`1756107600`	Unix timestamp in seconds; 5-minute clock skew allowed by default
`X-Nonce`Required	Header	string	`n7Kq2mR9xL4pQw8Z`	16–128 character URL-safe nonce (A-Za-z0-9_-), unique per request
`X-Signature`Required	Header	string	`a1b2c3d4e5f6...`	HMAC-SHA256 of the canonical request, lowercase hex

Field	In	Type	Example	Description
`id`Required	Response	uuid	`199ce8d6-788c-41cd-b3d9-b87abe8f35fa`	User ID
`username`Required	Response	string	`admin`	Username
`email`Required	Response	string	`admin@auth-one.local`	Email
`status`Required	Response	string	`active`	Account status, such as active / inactive
`roles`	Response	object[] \| null	`[{...}]`	Roles; null when none are assigned
`id`Required	Response	uuid	`b826ef2c-62ac-4ad9-aefa-02c6d0048d4f`	Role ID
`code`Required	Response	string	`admin`	Role code
`name`Required	Response	string	`admin`	Role name
`departments`	Response	object[] \| null	`[{...}]`	Departments; null when none are assigned
`id`Required	Response	uuid	`df2d69ab-56a9-43bf-8999-d60995719001`	Department ID
`code`Required	Response	string	`HQ`	Department code
`name`Required	Response	string	`HQ`	Department name
`positions`	Response	object[] \| null	`[{...}]`	Positions; null when none are assigned
`id`Required	Response	uuid	`e0f37812-21fb-47df-ad35-417fd4badff1`	Position ID
`name`Required	Response	string	`Admin`	Position name
`hash`Required	Response	string	`cfe7e40f3bbc7be47aea69b5803f366a...`	Integrity hash of the user record
`created_at`Required	Response	datetime	`2026-08-13T09:27:29+08:00`	Created at (ISO 8601 with time zone)
`updated_at`Required	Response	datetime	`2026-08-13T09:27:29+08:00`	Updated at (ISO 8601 with time zone)

Health check

GET/healthNo auth

Process liveness check

Checks whether the HTTP process can serve traffic. No authentication required. Dependency readiness is exposed on the protected /readyz endpoint.