Users

6 endpoints

Manage directory users in WordAuth OS. Paths are relative to your app domain under /api.

users.read

users.write

Manage directory users in WordAuth OS. Paths are relative to your app domain under /api.

Authenticate with your organization API key. Include subOrgId as a query parameter or in the request body when using an org-wide key. Organization-scoped keys automatically target their organization.

GET

/v1/users

List directory users. Org-wide API keys may omit subOrgId to include all organizations.

Request Headers

Param	Type	Required	Description
X-API-Key	string	Yes	Your WordAuth API key

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "users": [ /* directory user objects */ ] }

POST

/v1/users

Create a directory user in the target organization. Requires users.write.

Request Body

Param	Type	Required	Description
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.
email	string	Yes	User email address
displayName	string \| null	No	Display name
firstName	string \| null	No	First name
lastName	string \| null	No	Last name
phone	string \| null	No	Phone number
jobTitle	string \| null	No	Job title
department	string \| null	No	Department
externalId	string \| null	No	External ID from your system

Response — 200

{ "user": { /* directory user object */ } }

PUT

/v1/users

Create up to 500 directory users in one request. Requires users.write.

Request Body

Param	Type	Required	Description
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.
users	object[]	No	Array of user objects (alternative to bulkText)
bulkText	string	No	Newline-delimited bulk import text

Response — 200

{ "created": [ /* user objects */ ], "skipped": [ { "email": "...", "reason": "..." } ], "failed": [ { "email": "...", "error": "..." } ] }

PATCH

/v1/users/{userId}

Update directory user profile fields or active status. Requires users.write.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Request Body

Param	Type	Required	Description
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.
displayName	string \| null	No	Display name
firstName	string \| null	No	First name
lastName	string \| null	No	Last name
phone	string \| null	No	Phone number
jobTitle	string \| null	No	Job title
department	string \| null	No	Department
externalId	string \| null	No	External ID from your system
active	boolean	No	Whether the user is active

Response — 200

{ "user": { /* updated user object */ } }

DELETE

/v1/users/{userId}

Delete a directory user from an organization. Requires users.write.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.

Response — 200

{ "ok": true }

POST

/v1/users/{userId}

Move a user to a different organization. Requires users.write.

Request Body

Param	Type	Required	Description
targetSubOrgId	string	Yes	Organization to assign the user to

Response — 200

{ "user": { /* user in target sub-org */ } }

POST

/v1/users/invites

Create (or reuse) a directory user and send an invite email to set a password. Requires users.write.

Request Body

Param	Type	Required	Description
subOrgId	string	Yes	Organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one organization.
email	string	Yes	User email address
displayName	string \| null	No	Display name
firstName	string \| null	No	First name
lastName	string \| null	No	Last name

Response — 200

{ "user": { /* directory user */ }, "invite": { "id": "...", "email": "...", "status": "pending" } }

POST

/v1/users/{userId}/invite

Send an invite email to an existing directory user. Requires users.write.

Response — 200

{ "invite": { "id": "...", "status": "pending" } }

POST

/v1/users/{userId}/password/reset

Admin-triggered password reset email for a directory user. Requires users.write and password reset enabled.

Response — 200

{ "delivery_hint": "j•••@example.com" }

PUT

/v1/users/{userId}/password

Force-set a password for a directory user (creates an auth account if needed). Requires users.write.

Request Body

Param	Type	Required	Description
password	string	Yes	User password (min 8 characters for signup)
revokeSessions	boolean	No	When true (default), revoke all existing sessions after setting the password

Response — 200

{ "ok": true, "auth_user_id": "..." }

POST

/v1/users/{userId}/verify/resend

Resend email verification for a directory user with an unconfirmed auth account. Requires users.write.

Response — 200

{ "delivery_hint": "j•••@example.com" }

DELETE

/v1/users/{userId}/sessions

Revoke all active sessions for a directory user. Requires sessions.revoke.

Response — 200

{ "revoked": 2 }