Domain operations

The Devo Provisioning API allows users to perform the following operations related to domains and users in a given domain:

1 Fetch domain users' info
2 Delete a user from a domain
3 Disable a user in a domain
4 Enable a user in a domain
5 Update a domain user's role
6 Create users in a domain
7 Change domain owner

Fetch domain users' info

You can perform the following related operations:

`GET /user/domain/{domain}`

Returns the information of all the users in a given domain.

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

Returns information about a specific user given the domain it belongs to and its email.

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

Returns information about a specific user given the domain it belongs to and its external ID.

Delete a user from a domain

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

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

All users in a domain can be deleted, except for the one assigned as owner. Trying to remove the owner results in the following error:

{
  "error": {
    "code": 112,
    "message": "Domain owner can not be deleted"
  }
}

Disable a user in a domain

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

Disables a user in a given domain, denying access to it.

Trying to disable an already disabled domain will return the following error:

HTTP/1.1 400 Bad Request
{
  "error": {
    "code": 116,
    "message": "Error disabling a non inactive user. User user@company.com at domain mydomain"
  }
}

Enable a user in a domain

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

Enables a previously disabled user in a given domain.

Response example

{
  "email" : "user@company.com",
  "userName" : "user",
  "role" : "reviewer,NO_PRIVILEGES", 
  "domain" : "basic@company",
  "owner" : false,
  "status" : "active"
}

If you try to enable an already enabled user domain, you will get the following error:

Update a domain user's role

The Provisioning API has two different options when trying to change a domain user's role:

`PUT /user/email/{email}/domain/{domain}/role/{roleName}`

Use this operation to update the role of users with a single role, indicating the email and domain of the user and the new role.

`PUT /user/email/{email}/domain/{domain}/role`

Use this operation to update the roles of users with several roles assigned, replacing the current ones with the new specified set. The request body must include a JSON listing all the new role names as in the following example:

The multi-role endpoint does not return an error even if no update is actually done (for example, because the user already had the required roles).

Note that the role of the domain owner cannot be updated. Trying to do so will result in the following error:

A similar message is returned when the user already has the role we are trying to set.

Keep in mind that the Admin role cannot be combined with any other role.

Create users in a domain

To create a new user in a domain, different operations must be used depending on the type of credentials (common or reseller domain). The platform allows two different types of users, internal and external.

Internal users - They are registered into the platform with their own password. Internal users are required to validate their email and are the only ones that can be added as domain owners.
External users - Users that 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 can not be domain owners.

Since the API previously did not consider domain-level credentials, the requests can be sent to:

`POST /user/internal`

`POST /user/external`

An example of the request body required:

The default values for the role param are either ADMIN or NO_PRIVILEGES.
Always enter the full domain name in the domain value. Requests including domain names without the @{resellerName} tail will fail.

A properly configured request will return a response like this:

To create an owner, use the role OWNER when creating the user domain. Note that each domain can only have one owner.
Creating a new user in a domain leaves the status value as pending until the user validates the verification email sent by the system.

When you assign an already existing user to a domain using reseller credentials, you can skip the email validation step. For this to work there are several conditions:

The request includes the query param skipMailValidation=true.
The user already exists, is validated and has 'active' status.
The user is not an external user (it has credentials in the platform).

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:

To assign a user (new or existing) as a domain owner, use the role OWNER when creating the user domain. This will create the user domain with role ADMIN and set the OWNER flag.
Owners cannot be deleted from the domain they own.
Updating a role requires all required roles to be available, otherwise an error will be returned.
The ADMIN and NO_PRIVILEGES roles are present by default, and cannot be updated or deleted. An error may be returned in this case, since only custom roles are included in the query.
Owners must always have the Admin role.
The Admin role 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 (along with a boolean OWNER flag).

Change domain owner

To change a domain owner, just send a request to the following endpoint:

`PUT /domain/{domainName}/owner/{ownerEmail}`

This just returns a 200 HTTP status code (OK), but requires the following to be true:

The new owner email must exist and have access to the required domain.
The new owner role must be Admin.