The user endpoint lets you maintain user data, reset passwords, and maintain role assignment.

Creating and updating users

The Pure API lets you maintain both internally authenticated users where Pure stores passwords and handles authentication, and externally authenticated users where credentials are not stored in Pure and authentication is handled by another system. The externallyAuthenticated field is used to separate internally authenticated users from externally authenticated users.

A password is not specified as part of creating an internally authenticated user, so the end-user cannot log into Pure until a password reset has been performed. Creating an internally authenticated user using the Pure API is most often immediately followed by using the Pure API to invoke a password reset. When you reset the password of a user using the Pure API, an e-mail with a password reset link will be sent to the e-mail address of the user.

You can use the Pure API to get an end-user to set an initial password when an internally authenticated user has just been created, or you can use it to help internally authenticated end-users who have forgotten their password.

Working with roles

The Pure API works with roles in two areas:

• The role endpoint: Information about roles that can be assigned.
• The user endpoint: Maintenance of roles assigned to users.

The Pure API works with local and global roles:

Information about assignable roles

You use the role endpoint to get information about roles that can be assigned to users. Normally, the role endpoint is not actively used by your Pure API client. You use it to get to know what a role is called before writing code that assigns it to users. You can also use it to resolve information about an assignable role when you encounter a reference to an assignable role.

Roles assigned to users

You use the user endpoint to see and update what roles have been assigned to a specific user. The roles sub-resource of a user handles both global and local roles at the same time.

Requests for local and global roles work with the complete picture of a user's local and global roles; you get the complete picture of a user's local and global roles when you fetch roles and you perform updates by sending an updated complete picture of a user's local and global roles.

This means that to assign the local role 'equipment-editor' on an additional organization, you need to:

1. Fetch existing roles of the user you want to assign the 'equipment-editor' role to.
2. Add the information on which organization to assign the 'equipment-editor' role to the local roles part.
3. Send the updated document back to the Pure API.

Similarly, to remove this role (on a particular organization) from the user you need to:

1. Fetch existing roles of the user.
2. Remove the information that indicates the role was assigned to that particular organization from the local part.
3. Send the updated document back to the Pure API.

If you want to modify the global roles, change the global roles part of the fetched roles. Global roles do not require a target content item to be specified, so here you only add or remove the global role by name.

Bulk role updates

Multiple role additions and multiple role removals can be applied by sending an updated document that contains all changes in one request. 

Sending an empty document will cause all local and global roles to be removed from a user.