New Admins: Register for our new Pure Lecture Series!
Pure's logos
Pure Help Center for Pure Administrators

If you are a researcher, or other non-admin at your institution, click here.

  • Home
  • Announcements
  • Release Notes
  • Technical user guides
  • Training
  • Events
  • Support
  • Contact Us
  • Home
  • Training
  • Technical user guides
  • Pure API

How Can We Help?

Search Results

Filter By Category

Contact Us

If you still have questions or prefer to get help directly from an agent, please submit a request.
We’ll get back to you as soon as possible.

Contact us

Pure API: Users and rolesPure API: Users and roles

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:

Kind Targets content Example
Local role Yes 'equipment-editor' that is assigned on specific organizations and only allows access where the role is assigned
Global role No 'equipment-administrator' that allows access across all organizations

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. 

It is more efficient to perform multiple role updates in a single request than performing multiple requests with a single update in each. Additionally, role updates are atomic. 

Should a role update fail "in the middle" of processing, then nothing is persisted.

 

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

 

 

Published at December 12, 2024

Download
Table of Contents
  1. Creating and updating users
  2. Working with roles
  3. Information about assignable roles
  4. Roles assigned to users
  5. Bulk role updates
Related Articles
  • Getting started: Pure API user guide
  • Pure API: Access definitions for content and field filtering
  • Testing the Pure API: A Beginner's Guide
  • Testing the Pure API Using RapiDoc
  • Python API Requests: Fundamental Coding Examples
Keywords
  • permissions
  • identities

Was this article helpful?

Yes
No
Give feedback about this article

    About Pure

  • Announcements

    Additional Support

  • Events
  • Client Community
  • Training

    Need Help?

  • Contact Us
  • Submit a Support Case
  • My Cases
  • Linkedin
  • Twitter
  • Facebook
  • Youtube
Elsevier logo Relx logo

Copyright © 2025 Elsevier, except certain content provided by third parties.

  • Terms & Conditions Terms & Conditions
  • Privacy policyPrivacy policy
  • AccesibilityAccesibility
  • Cookie SettingsCookie Settings
  • Log in to Pure Help CenterLog in to Helpjuice Center

Knowledge Base Software powered by Helpjuice

Expand