Users

6 endpoints

Manage directory users in WordAuth OS. Base URL: your app domain — paths below are under /api.

users.read

users.write

Manage directory users in WordAuth OS. Base URL: your app domain — paths below are under /api.

GET

/v1/users

List directory users. Org-wide API keys may omit subOrgId to include all sub-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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

Response — 200

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

POST

/v1/users

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

Request Body

Param	Type	Required	Description
subOrgId	string	Yes	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.
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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.
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	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

Request Body

Param	Type	Required	Description
subOrgId	string	Yes	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.
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 a sub-organization. Requires users.write.

Query Parameters

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

Response — 200

{ "ok": true }

POST

/v1/users/{userId}

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

Request Body

Param	Type	Required	Description
targetSubOrgId	string	Yes	Sub-organization to assign the user to

Response — 200

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