Users

List users

Example Request:

curl "https://controller-host:8001/api/v2/users" \
	-X GET \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "users": [
        {
            "username": "admin@example.com",
            "displayName": "Admin",
            "roles": [
                "admin"
            ],
            "disabled": false
        },
        {
            "username": "user@example.com",
            "displayName": "User",
            "roles": [
                ""
            ],
            "disabled": false
        }
    ],
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 2
}

Return a list of users.

This endpoint is restricted to the following roles: admin, super admin

HTTP Request

GET /api/v2/users

Request Parameters

These parameters should be added to the URL as a query string.

Name	Type	Description	Default Value
username (optional)	string	Username substring to filter by
displayName (optional)	string	Display name substring to filter by
roles (optional)	string	Comma separated list of user roles to filter by
authenticationTypes (optional)	string	Comma separated list of authentication types to filter by
disabled (optional)	boolean	Whether the users are disabled or not
page (optional)	int	Page number to return	1
perPage (optional)	int	Number of users to return per page	25

Returns

Returns a list of users a UserList object with the following attributes:

Name	Type	Description
users	array of objects	List of users as an array of User objects
page	int	Page number returned
perPage	int	Number of users returned per page
totalPages	int	Total number of pages available
totalItems	int	Total number of users

Create a user

Example Request:

curl "https://controller-host:8001/api/v2/users" \
	-X POST \
	-u u_jsmith@example.com_u0VmztKJrwqf: \
	-d displayName="User" \
	--data-urlencode username="user@example.com"

Example Response:

{
    "username": "user@example.com",
    "displayName": "User",
    "roles": [
        ""
    ],
    "disabled": false
}

Create a new user and optionally specify a password.

This endpoint is restricted to the following roles: admin, super admin

This endpoint is not available for LDAP/SAML users.

HTTP Request

POST /api/v2/users

Request Parameters

Name	Type	Description	Default Value
username	string	Email address of user
displayName	string	Name of the user to display
roles (optional)	string	Roles to assign user; only one role should be specified in the list
password (optional)	string	Must be at least 6 characters in length; if not set, an automatically-generated password will be sent to the user's email address

Returns

Returns the newly-created user as a User object with the following attributes:

Name	Type	Description
username	string	Email address of user
displayName	string	Name of the user to display
roles	string	Role assigned to user
authenticationType	string	How the user is authenticated
disabled	boolean	Whether the user has been disabled

Roles

There are five possible roles that a user can be assigned as.

Role
Super Admin
Admin
Linguist
Translator
Observer

Update a user

Example Request:

curl "https://controller-host:8001/api/v2/users/user@example.com" \
	-X PUT \
	-u u_jsmith@example.com_u0VmztKJrwqf: \
	-d displayName="Manager" \
	-d roles="admin"

Example Response:

{
    "username": "user@example.com",
    "displayName": "Manager",
    "roles": [
        "admin"
    ],
    "disabled": false
}

Change a user's display name or role. Usernames cannot be changed.

This endpoint is restricted to the following roles: admin, super admin

This endpoint is not available for LDAP/SAML users.

HTTP Request

PUT /api/v2/users/{username}

Path Parameters

Name	Type	Description
username	string	Username (email address) of user

Request Parameters

Name	Type	Description	Default Value
displayName (optional)	string	New name of the user to display
roles (optional)	string	Roles to assign user; only one role should be specified in the list

Returns

Returns the updated user as a User object.

Retrieve a user

Example Request:

curl "https://controller-host:8001/api/v2/users/user@example.com" \
	-X GET \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "username": "user@example.com",
    "displayName": "User",
    "roles": [
        ""
    ],
    "disabled": false
}

Return information about a user.

This endpoint is restricted to users with the following roles only (except when specifying the current user with the special value of me): admin, super admin.

HTTP Request

GET /api/v2/users/{id}

Path Parameters

Name	Type	Description
id	string	Identifier of user: username or access token, depending on the value of field; if field is username, the special value of me must be used in order to refer to the currently authenticated user

Request Parameters

These parameters should be added to the URL as a query string.

Name	Type	Description	Default Value
field (optional)	string	Field by which to look up user (possible choices: username or accessToken)	username

Returns

Returns the specified user as a User object.

Create a reset password request by a regular user.

Example Request:

curl "https://controller-host:8001/api/v2/users/user@example.com/password/request-reset-self" \
	-X POST

Example Response:

{
    "username": "user@example.com",
    "resetPasswordUrl": "The password reset instructions have been sent to your email",
    "expirationInHours": 24
}

Create a reset password request, and email it to a user's email address. This call will fail if SMTP is not configured.

This endpoint does not require authentication.

This endpoint is not available for LDAP/SAML users.

HTTP Request

POST /api/v2/users/{username}/password/request-reset-self

Path Parameters

Name	Type	Description
username	string	Username (email address) of user

Returns

Returns a ResetPasswordRequest object with the following attributes:

Name	Type	Description
username	string	Username and email address of user to which reset password request was sent (if SMTP was enabled)
resetPasswordUrl	string	A message informing the user to check their email. The secret token is hidden for security reasons
expirationInHours	int	Hours until reset password URL expires

Create a reset password request by an Administrator

Example Request:

curl "https://controller-host:8001/api/v2/users/user@example.com/password/request-reset" \
	-X POST \
	-u u_jsmith@example.com_u0VmztKJrwqf: \
	--data-urlencode callbackUrl="https://your-app:7777/reset-password"

Example Response:

{
    "username": "user@example.com",
    "resetPasswordUrl": "https://your-app:7777/reset-password?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
    "expirationInHours": 24
}

Create a reset password request, and optionally email it to the user. If SMTP is not configured, no email will be sent. For custom integrations with this API, a webpage will need to be set up where the user can be sent to change their password. In the example to the right, https://your-app:7777/reset-password is the callback URL, and notice that the reset password token is appended as a token query string parameter.

This endpoint is not available for LDAP/SAML users.

HTTP Request

POST /api/v2/users/{username}/password/request-reset

Path Parameters

Name	Type	Description
username	string	Username (email address) of user

Request Parameters

Name	Type	Description	Default Value
callbackUrl (optional)	string	URL to which a reset token is appended (as the query string parameter token) and which is emailed to the user	[private web URL]
suppressEmail (optional)	boolean	If true, do not send an automated email to the user's email address	false

Returns

Returns a ResetPasswordRequest object with the following attributes:

Name	Type	Description
username	string	Username and email address of user to which reset password request was sent (if SMTP was enabled)
resetPasswordUrl	string	URL where user can reset their password; URL included in the reset password request email
expirationInHours	int	Hours until reset password URL expires

Change a user's password with the old password

Example Request:

curl "https://controller-host:8001/api/v2/users/user@example.com/password" \
	-X PUT \
	-u u_jsmith@example.com_u0VmztKJrwqf: \
	-d newPassword="newPassword" \
	-d oldPassword="noMaxLength"

Example Response:

{
    "username": "user@example.com",
    "displayName": "User",
    "roles": [
        ""
    ],
    "disabled": false
}

Change a user's password by providing the old password and requiring it to match the existing password. Admin users can change the password of any user, while non-admin users can only change their own password using the special username value of me.

This endpoint is restricted to users with the following roles only (except when specifying the current user with the special value of me): admin, super admin.

This endpoint is not available for LDAP/SAML users.

HTTP Request

PUT /api/v2/users/{username}/password

Path Parameters

Name	Type	Description
username	string	Username (email address) of user; the special value of me must be used in order to refer to the currently authenticated user

Request Parameters

Name	Type	Description	Default Value
oldPassword	string	Old password that must be valid before password can be changed
newPassword	string	New password that must be at least 8 characters in length and have at least 3 of the following: lowercase character, uppercase character, number, and symbol

Returns

Returns the updated user (new password not included for security reasons) as a User object.

Change a user's password with a reset token

Example Request:

curl "https://controller-host:8001/api/v2/users/user@example.com/password/reset-token" \
	-X PUT \
	-d newPassword="newPassword" \
	--data-urlencode resetToken="<token>"

Example Response:

{
    "username": "user@example.com",
    "displayName": "User",
    "roles": [
        ""
    ],
    "disabled": false
}

Change a user's password by providing a valid reset token, which is obtained by first creating a reset password request.

This endpoint does not require authentication.

This endpoint is not available for LDAP/SAML users.

HTTP Request

PUT /api/v2/users/{username}/password/reset-token

Path Parameters

Name	Type	Description
username	string	Username (email address) of user

Request Parameters

Name	Type	Description	Default Value
resetToken	string	Reset token that must be valid before password can be changed
newPassword	string	New password that must be at least 8 characters in length and have at least 3 of the following: lowercase character, uppercase character, number, and symbol

Returns

Returns the updated user (new password not included for security reasons) as a User object.

Retrieve API credentials for the current user

Example Request:

curl "https://controller-host:8001/api/v2/users/me/credentials" \
	-X GET \
	-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gU21pdGgiLCJpYXQiOjE1MTYyMzkwMjJ9.Q_w2AVguPRU2KskCXwR7ZHl09TQXEntfEA8Jj2_Jyew"

Example Response:

{
    "key": "u_user@example.com_r7eHQ7t9o1Jb"
}

Retrieve the API credentials for the current user. In case you need to recover your API key, you can call this endpoint using token authentication, provided you know your username and password.

HTTP Request

GET /api/v2/users/me/credentials

Returns

Returns the current user's API credentials as an ApiCredentials object with the following attributes:

Name	Type	Description
key	string	Key for accessing Language Weaver Edge REST API as the current user

Change API credentials for the current user

Example Request:

curl "https://controller-host:8001/api/v2/users/me/credentials" \
	-X PUT \
	-u u_jsmith@example.com_u0VmztKJrwqf: \
	--data-urlencode key="u_user@example.com_bluebird"

Example Response:

{
    "key": "u_user@example.com_bluebird"
}

Change the API credentials for the current user.

HTTP Request

PUT /api/v2/users/me/credentials

Request Parameters

Name	Type	Description	Default Value
key	string	New API key to change to. It must be of the form u_username_string, where username is the current user's username, string consists of letters and/or numbers, and the entire key is at most 255 characters long (e.g., u_user@example.com\_bluebird).

Returns

Returns the updated API credentials as an ApiCredentials object.

Delete a user

Example Request:

curl "https://controller-host:8001/api/v2/users/user@example.com" \
	-X DELETE \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "username": "user@example.com",
    "displayName": "User",
    "roles": [
        ""
    ],
    "disabled": false
}

Delete a user's account and all of their translations. No notification will be sent to the user's email address.

This endpoint is restricted to the following roles: admin, super admin

This endpoint is not available for LDAP/SAML users.

HTTP Request

DELETE /api/v2/users/{username}

Path Parameters

Name	Type	Description
username	string	Username (email address) of user

Returns

Returns the deleted user as a User object.

Delete users

Example Request:

curl "https://controller-host:8001/api/v2/users/batch-delete" \
	-X DELETE \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

1

Delete users' account and all of their translations. No notification will be sent to the users' email addresses.

This endpoint is restricted to the following roles: admin, super admin

This endpoint is not available for LDAP/SAML users.

HTTP Request

DELETE /api/v2/users/batch-delete

Request Parameters

These parameters should be added to the URL as a query string.

Name	Type	Description	Default Value
usernames (optional)	string	Comma separated username substrings to filter by
displayName (optional)	string	Display name substring to filter by
roles (optional)	string	Comma separated list of user roles to filter by
authenticationTypes (optional)	string	Comma separated list of authentication types to filter by
disabled (optional)	boolean	Whether the users are disabled or not

Returns

Returns the number of deleted users.