Document toolboxDocument toolbox

User operations

Owned by Juan Tomás Alonso Nieto (Deactivated)
Last updated: Aug 31, 2024
12 min read
[ 1 Overview ] [ 2 Endpoints and methods ]

Overview

Check the list of available endpoints and methods to create and modify users using the Provisioning API.

Internal and external users

Some of the actions you can perform using these endpoints apply to different groups of users (internal and external users) so it’s important to know the difference between them:

  • Internal users are registered into the platform with their own password. Internal users are required to validate their email, and they can be added as domain owners.

  • External users are registered into a third party platform, and have limited access to the platform. They need to be registered as external users, but do not need to have their emails validated. They cannot be domain owners.

Endpoints and methods

Description

Endpoints and methods

Description

GET /user/email/{userEmail} see below

Get user info based on email.

GET /user/domain/{domainName} see below

Get information about the users in a domain.

GET /user/email/{userEmail}/domain/{domainName} see below

Get user info based on email and domain.

GET /user/internal/{id} see below

Get user info based on internal ID

GET /user/internal/{id}/domain/{domainName} see below

Get user info based on domain and internal ID.

GET /user/external/{id}/domain/{domainName} see below

Get user info based on domain and external ID.

POST /user/internal see below

Add an internal user to a domain.

POST /user/external see below

Add an external user to a domain.

POST /user/email/{userEmail}/domain/{domainName}/disable see below

Disable a user in a domain.

POST /user/email/{userEmail}/domain/{domainName}/enable see below

Enable a user in a domain.

PUT /user/email/{userEmail}/domain/{domainName}/role see below

Set the roles of a user in a domain.

PUT /user/email/{userEmail}/domain/{domainName}/role/{roleName} see below

Change the role of a user in a domain.

PUT /user/internal/{id} see below

Update user info.

DELETE /user/email/{userEmail}/domain/{domainName} see below

Delete a user from a domain.

DELETE /user/email/{userEmail}/domain/{domainName}/role see below

Remove roles from a user.

Endpoints and methods

GET /user/email/{userEmail}

Get basic user info based on email. The information retrieved is not related to any specific domain.

Path parameters

Add the following path parameters as part of the endpoint:

Parameter

Type

Description

Parameter

Type

Description

userEmail required

string

Enter the email of the required user.

Find below a request example:

https://api-us.devo.com/probio/user/email/user@devo.com

Code

Description

Code

Description

200

Successful response. User info retrieved.

{ "email": "user@devo.com", "userName": "John", "phone": "678345678", "id": "2456-sgfd-2344" }

4xx

Bad request.

{ "error": { "code": 4xx, "message": "string" } }

GET /user/domain/{domainName}

Get basic information about all the users in a given domain.

Path parameters

Add the following path parameters as part of the endpoint:

Parameter

Type

Description

Parameter

Type

Description

domainName required

string

Enter the name of the required domain. You must enter the full domain name using the format {domainName}@{resellerName}

Find below a request example:

Code

Description

Code

Description

200

Successful response. User info retrieved.

4xx

Bad request.

GET /user/email/{userEmail}/domain/{domainName}

Get specific user info based on their email and domain.

This endpoint may be used with both regular and multitenant domains.

Path parameters

Add the following path parameters as part of the endpoint:

Parameter

Type

Description

Parameter

Type

Description

userEmail required

string

Enter the email of the required user.

domainName required

string

Enter the name of the required domain. If it is a multitenant domain, you must enter the full domain name using the format {domainName}@{resellerName}

Find below a request example:

GET /user/internal/{id}

Get basic user info based on internal ID. Note that this info is not related to any specific domain.

We recommend identifying users by email address instead of internal ID whenever possible.

GET /user/internal/{id}/domain/{domainName}

Get user info based on domain and internal ID.

GET /user/external/{id}/domain/{domainName}

Get user info based on domain and external ID.

POST /user/internal

Add an internal user to a multitenant domain.

Every user in a domain needs to have at least one role assigned to them, either one of the default roles in the application or a custom role. While creating users in a domain, keep in mind the following restrictions:

  • Internal users cannot be used immediately after creation - they must first be activated through a link sent to the email address provided. The activation process also requires the user to create a password.

  • The first user added to a new domain must be internal and must be the domain owner. Owners cannot be deleted, and a domain can only have one owner.

  • To assign a user (new or existing) as a domain owner, use the role OWNER when creating the user. This will create the user with the role ADMIN but with OWNER privileges. The ADMIN role is exclusive and cannot be combined with other roles.

  • This method can be also used to add an existing user to a different domain. In this case, the user will keep their original user name and phone number, ignoring any new value provided for them. The field externalId is ignored too since it only has meaning for external users (who might not have a password in the platform).

POST /user/external

Add an external user to a multitenant domain.

Every user in a domain needs to have at least one role assigned to them, either one of the default roles in the application or a custom role. When you create external users in a domain, keep in mind the following restrictions:

  • An external ID must be provided for the user - normally a valid identifier at the client platform. This method only works for clients belonging to a multitenant structure.

  • External users cannot be domain owners. They also do not require a username and password if the reseller configuration allows for it through federated authentication.

POST /user/email/{userEmail}/domain/{domainName}/disable

Disable a user in a given domain. Note that this action does not remove the user from the domain. Users can be re-enabled anytime.

POST /user/email/{userEmail}/domain/{domainName}/enable

Enable a user in a given domain.

PUT /user/email/{userEmail}/domain/{domainName}/role

Set the roles of a user in a given domain.

PUT /user/email/{userEmail}/domain/{domainName}/role/{roleName}

Change the role of a user in a given domain. Note that this action does not add a role to the user’s current ones, but replace them by the selected one.

PUT /user/internal/{id}

Update the information of a user that is independent of any specific domain.

DELETE /user/email/{userEmail}/domain/{domainName}

Removes a user from a given domain. If the user only belongs to the given domain, all the information about the user will be deleted from the platform.

DELETE /user/email/{userEmail}/domain/{domainName}/role

Removes the indicated roles from the user in the specified domain.

Â