User operations
- Former user (Deleted)
- Virginia Camuñas Núñez
- Laszlo Frazer
- Former user (Deleted)
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 its 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 |
|---|---|
GET | Get user info based on email. |
GET | Get information about the users in a domain. |
GET | Get user info based on email and domain. |
GET | Get user info based on internal ID |
GET | Get user info based on domain and internal ID. |
GET | Get user info based on domain and external ID. |
POST | Add an internal user to a domain. |
POST | Add an external user to a domain. |
POST | Disable a user in a domain. |
POST | Enable a user in a domain. |
PUT | Set the roles of a user in a domain. |
PUT | Change the role of a user in a domain. |
PUT | Update user info. |
DELETE | Delete a user from a domain. |
DELETE | 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.
Request
Path parameters
Add the following path parameters as part of the endpoint:
Parameter | Type | Description |
|---|---|---|
|
| Enter the email of the required user. |
Find below a request example:
https://api-us.devo.com/probio/user/email/user@devo.com
Response
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.
Request
Path parameters
Add the following path parameters as part of the endpoint:
Parameter | Type | Description |
|---|---|---|
|
| Enter the name of the required domain. You must enter the full domain name using the format {domainName}@{resellerName} |
Find below a request example:
https://api-us.devo.com/probio/user/domain/domainName@resellerName
Response
Code | Description |
|---|---|
200 | Successful response. User info retrieved. [
{
"email": "user@devo.com",
"userName": "John",
"role": "ADMIN",
"domain": "demo@training",
"owner": true,
"status": "active",
"roleList": [
"ADMIN"
]
},
{
"email": "user2@devo.com",
"userName": "Rita",
"role": "NO_PRIVILEGES",
"domain": "demo@training",
"owner": false,
"status": "active",
"roleList": [
"NO_PRIVILEGES"
]
},
{
"email": "user3@devo.com",
"userName": "Lara",
"role": "NO_PRIVILEGES",
"domain": "demo@training",
"owner": false,
"status": "inactive",
"roleList": [
"NO_PRIVILEGES"
]
},
{
"email": "user4@devo.com",
"userName": "Mary",
"role": "NO_PRIVILEGES",
"externalId": "123-45-678",
"domain": "demo@training",
"owner": false,
"status": "inactive",
"roleList": [
"NO_PRIVILEGES"
]
},
{
"email": "user5@devo.com",
"userName": "Alex",
"role": "ADMIN",
"domain": "demo@training",
"owner": false,
"status": "active",
"roleList": [
"ADMIN"
]
}
] |
4xx | Bad request. {
"error": {
"code": 4xx,
"message": "string"
}
} |
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.
Request
Path parameters
Add the following path parameters as part of the endpoint:
Parameter | Type | Description |
|---|---|---|
|
| Enter the email of the required user. |
|
| 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:
https://api-us.devo.com/probio/user/email/user@devo.com/domain/domainName@resellerName
Response
Code | Description |
|---|---|
200 | Successful response. User info retrieved. {
"email": "user@devo.com",
"userName": "John",
"role": "ADMIN",
"domain": "demo@training",
"owner": true,
"status": "active",
"roleList": [
"ADMIN"
]
} |
4xx | Bad request. {
"error": {
"code": 4xx,
"message": "string"
}
} |
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.
Request
Path parameters
Add the following path parameters as part of the endpoint:
Parameter | Type | Description |
|---|---|---|
|
| Internal ID of the user. How to get the ID of an internal user? You can use the GET |
Find below a request example:
https://api-us.devo.com/probio/user/internal/2456-sgfd-2344
Response
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/internal/{id}/domain/{domainName}
Get user info based on domain and internal ID.
Request
Path parameters
Add the following path parameters as part of the endpoint:
Parameter | Type | Description |
|---|---|---|
|
| Internal ID of the user. How to get the ID of an internal user? You can use the GET |
|
| Enter the name of the required domain. You must enter the full domain name using the format {domainName}@{resellerName} |
Find below a request example:
https://api-us.devo.com/probio/user/internal/2456-sgfd-2344/domain/domainName@resellerName
Response
Code | Description |
|---|---|
200 | Successful response. User info retrieved. {
"email": "user@devo.com",
"userName": "John",
"role": "ADMIN",
"domain": "demo@training",
"owner": true,
"status": "active",
"roleList": [
"ADMIN"
]
} |
4xx | Bad request. {
"error": {
"code": 4xx,
"message": "string"
}
} |
GET /user/external/{id}/domain/{domainName}
Get user info based on domain and external ID.
Request
Path parameters
Add the following path parameters as part of the endpoint:
Parameter | Type | Description |
|---|---|---|
|
| External ID of the user. How to get the ID of an external user? You can use the GET If theres any external users, you will get their IDs in the response, in the |
|
| Enter the name of the required domain. You must enter the full domain name using the format {domainName}@{resellerName} |
Find below a request example:
https://api-us.devo.com/probio/user/external/2456-sgfd-2344/domain/domainName@resellerName
Response
Code | Description |
|---|---|
200 | Successful response. User info retrieved. {
"email": "user@devo.com,
"userName": "Rita",
"role": "ADMIN",
"externalId": "2456-sgfd-2344",
"domain": "domainName@resellerName",
"owner": false,
"status": "active",
"roleList": [
"ADMIN"
]
} |
4xx | Bad request. {
"error": {
"code": 4xx,
"message": "string"
}
} |
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.
Youll need the multitenant API keys to create the first user in the domain, and its role must be OWNER. Check an example of this below.
To assign a user (new or existing) as a domain owner, use the role
OWNERwhen creating the user. This will create the user with the roleADMINbut withOWNERprivileges. TheADMINrole is exclusive and cannot be combined with other roles.
Notice that even though the role OWNER is used to assign a user the ownership of a domain, this is interpreted as ADMIN role, flagged as OWNER, so the actual role (for policies, permissions) is actually ADMIN, and that value will be returned in the responses (along with a boolean OWNER flag).
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
externalIdis ignored too since it only has meaning for external users (who might not have a password in the platform).
Request
Query string parameters
Query string parameters are added after the path parameters, preceded by a question mark (?) and separated by an ampersand ()
Parameter | Type | Description |
|---|---|---|
|
| Set this to Note that in order to use this parameter, you must use multitenant domain credentials to authorize your request. |
Request body
The request JSON body must include the userInfo object with the following key-value pairs:
Parameter | Type | Description |
|---|---|---|
|
| Domain name. Must match the expression ^[A-Za-z]A-Za-z0-9_-?$. |
|
| Name of the new user. Must match the expression ^(([a-zA-Z0-9-])+([ _'.@-]))([a-zA-Z0-9-])$. This field will be ignored if you are adding an already existing user to a different domain, and the current value will be kept. |
|
| Enter the email address of the new user. |
|
| Role of the new user. Basic roles in Devo are:
Custom roles must match the expression ^(([a-zA-Z0-9])+([ _-]))([a-zA-Z0-9])$. Check more info about roles at the top of this endpoint section. |
|
| Phone number of the new user. Must match the expression ^+(?:[0-9] ?){6,14}[0-9]$. This field will be ignored if you are adding an already existing user to a different domain, and the current value will be kept. |
Find below a request example:
https://api-us.devo.com/probio/user/internal?skipValidation=falseAnd this is an example of a request body, including the required JSON object. In this example, we are adding the first user (owner) of a domain:
{
"domain": "domainName@resellerName",
"userName": "Frank",
"email": "user@devo.com",
"role": "OWNER"
}
Response
Code | Description |
|---|---|
200 | Successful response. User added to the given domain. {
"email": "user@devo.com",
"userName": "Frank",
"role": "ADMIN",
"domain": "domainName@resellerName",
"owner": true,
"status": "pending",
"roleList": [
"ADMIN"
]
} |
4xx | Bad request. {
"error": {
"code": 4xx,
"message": "string"
}
} |
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.
Request
Request body
The request JSON body must include the userInfo object with the following key-value pairs:
Parameter | Type | Description |
|---|---|---|
|
| Domain name. Must match the expression ^[A-Za-z]A-Za-z0-9_-?$. |
|
| Name of the new user. Must match the expression ^(([a-zA-Z0-9-])+([ _'.@-]))([a-zA-Z0-9-])$. |
|
| Enter the email address of the new user. |
|
| User identifier in the external system. The maximum number of characters is 256. |
|
| Role of the new user. Must match the expression ^(([a-zA-Z0-9])+([ _-]))([a-zA-Z0-9])$. |
|
| Phone number of the new user. Must match the expression ^+(?:[0-9] ?){6,14}[0-9]$. |
|
| Set this parameter to |
Find below a request example:
https://api-us.devo.com/probio/user/externalAnd this is an example of a request body, including the required JSON object:
{
"domain": "domainName@resellerName
"userName": "Lara",
"email": "user@devo.com",
"externalId": "12345",
"role": "ADMIN"
}
Response
Code | Description |
|---|---|
200 | Successful response. User added. {
"email": "user@devo.com",
"userName": "Lara",
"role": "ADMIN",
"externalId": "12345",
"domain": "domainName@resellerName",
"owner": false,
"status": "active",
"roleList": [
"ADMIN"
]
} |
4xx | Bad request. {
"error": {
"code": 4xx,
"message": "string"
}
} |
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.
Request
Path parameters
Add the following path parameters as part of the endpoint:
Parameter | Type | Description |
|---|---|---|
|
| Enter the email of the required user. |
|
| Enter the name of the required domain. You must enter the full domain name using the format {domainName}@{resellerName} |
Find below a request example:
https://api-us.devo.com/probio/user/email/user@devo.com/domain/domainName@resellerName/disable
Response
Code | Description |
|---|---|
200 | Successful response. User disabled. |
4xx | Bad request. {
"error": {
"code": 4xx,
"message": "string"
}
} |
POST /user/email/{userEmail}/domain/{domainName}/enable
Enable a user in a given domain.
Request
Path parameters
Add the following path parameters as part of the endpoint:
Parameter | Type | Description |
|---|---|---|
|
| Enter the email of the required user. |
|
| Enter the name of the required domain. You must enter the full domain name using the format {domainName}@{resellerName} |
Find below a request example:
https://api-us.devo.com/probio/user/email/user@devo.com/domain/domainName@resellerName/enable
Response
Code | Description |
|---|---|
200 | Successful response. User enabled. |
4xx | Bad request. {
"error": {
"code": 4xx,
"message": "string"
}
} |
PUT /user/email/{userEmail}/domain/{domainName}/role
Set the roles of a user in a given domain.
Request
Path parameters
Add the following path parameters as part of the endpoint:
Parameter | Type | Description |
|---|---|---|
|
| Enter the email of the required user. |
|
| Enter the name of the required domain. You must enter the full domain name using the format {domainName}@{resellerName} |
Query string parameters
Query string parameters are added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&).
Parameter | Type | Description |
|---|---|---|
|
| Set this to |
Request body
The request JSON body must include the following key-value pairs:
Parameter | Type | Description |
|---|---|---|
|
| Enter the list of role names separated by commas. Basic roles in Devo are:
Custom roles must match the expression ^(([a-zA-Z0-9])+([ _-]))([a-zA-Z0-9])$. |
Find below a request example:
https://api-us.devo.com/probio/user/email/user@devo.com/domain/domainName@resellerName/role?keepExisting=trueAnd this is an example of a request body, including the required JSON object:
[
"role1", "role2", "role3"
]
Response
Code | Description |
|---|---|
200 | Successful response. Roles updated. |
4xx | Bad request. {
"error": {
"code": 4xx,
"message": "string"
}
} |
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 users current ones, but replace them by the selected one.
Request
Path parameters
Add the following path parameters as part of the endpoint:
Parameter | Type | Description |
|---|---|---|
|
| Enter the email of the required user. |
|
| Enter the name of the required domain. You must enter the full domain name using the format {domainName}@{resellerName} |
|
| Name of the new role for the user. |
Find below a request example:
https://api-us.devo.com/probio/user/email/user@devo.com/domain/domainName@resellerName/role/role1
Response
Code | Description |
|---|---|
200 | Successful response. Role changed. |
4xx | Bad request. {
"error": {
"code": 4xx,
"message": "string"
}
} |
PUT /user/internal/{id}
Update the information of a user that is independent of any specific domain.
Request
Path parameters
Add the following path parameters as part of the endpoint:
Parameter | Type | Description |
|---|---|---|
|
| ID of the user to be updated. |
You can use either the query string parameters or request body indicated below to provide the updated values. If a request body is sent, the query string parameters will be ignored.
To delete an existing user value (like the phone number), set the field value to an empty string. To keep the existing value and not change it, either don't include the field in the request or set the field value to null.
Query string parameters
Query string parameters are added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&).
Parameter | Type | Description |
|---|---|---|
|
| New email address of the user. |
|
| New phone number of the user. Must match the expression ^+(?:[0-9] ?){6,14}[0-9]$. |
|
| New name of the user. Must match the expression ^(([a-zA-Z0-9-])+([ _'.@-]))([a-zA-Z0-9-])$. |
Request body
The request JSON body must include the following key-value pairs:
Parameter | Type | Description |
|---|---|---|
|
| New email address of the user. |
|
| New phone number of the user. Must match the expression ^+(?:[0-9] ?){6,14}[0-9]$. |
|
| New name of the user. Must match the expression ^(([a-zA-Z0-9-])+([ _'.@-]))([a-zA-Z0-9-])$. |
Find below a request example:
https://api-us.devo.com/probio/user/internal/123-456-789