Create user

post

https://staging.ankatech.co/api/v3/admin/tenants/{tenantId}/users

Creates a new user under the specified tenant.

Two provisioning modes:
• Secure mode (recommended): Set requirePasswordChange=true, omit password.
User receives activation link and sets their own password (zero-knowledge provisioning).
• Quick mode (testing): Set requirePasswordChange=false, include password.
User can login immediately.

Response includes:
• User details (always)
• Activation information (if requirePasswordChange=true): token, expiration, activation URL

The password is securely hashed before storage. If requirePasswordChange=true and no password
is provided, a secure random password is generated internally (user never sees it).

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

tenantId

uuid

required

Body Params

Request payload for creating a new HUMAN user account within a tenant.

Two provisioning modes:
• Secure mode (recommended): Set requirePasswordChange=true, omit password.
User receives activation link and sets their own password.
• Quick mode (testing): Set requirePasswordChange=false, include password.
User can login immediately.

Email addresses must be unique within the tenant (case-insensitive comparison).

string

required

length between 0 and 320

Email address serving as the unique login identifier for the user within the tenant.
Must be a valid RFC 5322 email address. This value is case-insensitive and must be
unique across all users in the same tenant. Used for authentication and communication.

password

length ≥ 8

OPTIONAL - Initial password for the user account.

When to include:
• requirePasswordChange=false (quick provisioning): REQUIRED - User can login immediately.
• requirePasswordChange=true (secure provisioning - DEFAULT): OPTIONAL - If omitted, a secure random
password is generated internally. The user will set their own password during account activation.

Password requirements (if provided):
• Minimum 8 characters
• At least one uppercase letter (A-Z)
• At least one lowercase letter (a-z)
• At least one digit (0-9)

Security Note: For production use, it is recommended to omit this field and use requirePasswordChange=true,
following industry best practices (AWS Cognito, Azure AD, Auth0 pattern). This ensures zero-knowledge
provisioning where admins never see user passwords.

requirePasswordChange

boolean

Defaults to true

Whether to require the user to change their password on first login (default: true).

• true (default - RECOMMENDED): The user must activate their account via an activation token
before accessing any protected resources. The response will include an activation token that
is delivered to the user via email as a deep-link to the Admin Console activation page
(e.g., https://console.ankatech.co/activate?token=...). This follows
OWASP ASVS 2.1.1 and industry best practices (AWS Cognito, Azure AD, Auth0).

• false: The password is permanent and can be used immediately for login. Use this for
automated integrations, testing, or bulk provisioning where password rotation is handled externally.

Security Note: When enabled (true - default), the response will include activation token metadata.
The user must use this token to set their own password before being able to login.

displayName

string

length between 0 and 255

Optional human-readable display name for UI presentation. This name does not need
to be unique and is used for user identification in interfaces. If not provided,
the email address will typically be used for display purposes.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

Credentials

Bearer

JWT

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json

201The user was created. The Location header carries the URI of the new user. The activation member is present ONLY when requirePasswordChange=true; its token is a single-use bearer that sets the password, so it is returned exactly once and never re-readable.

400The body failed validation — a missing or malformed email, a password below the configured policy, or a role name the tenant type does not admit. Raised during argument resolution (@Valid) or by the service before any row is written.

401Missing, invalid or expired token.

409A user with this loginId already exists in the tenant. Raised both by the pre-check and by the unique-constraint violation, so a concurrent duplicate answers 409 rather than 500.

500The user could not be persisted. The cause is suppressed from the body.

503User management is not wired in this deployment — the handler's own explicit refusal when HumanUserService is absent, not a transient outage.