Permissions and Roles

This page will detail how Permissions and Roles are structured to provide user access to different endpoints and resources in Data Refinery Designer. Implementing permissions and roles ensures that users only have access to relevant resources.

Table of contents

Permissions

Permissions are used to determine if a user can make a call to an API. These permissions are refinery-wide and give a user the ability to call certain endpoints or access specific resources. User permissions are grouped, and a user’s access is determined by the highest level of permission granted.

Review the different permissions, based on endpoint, in the table below.

Permission Name Endpoint GET PUT POST DELETE
USER_ADMIN /sso/oidc Y Y Y Y
USER_ADMIN /users Y Y Y Y
USER_CREATOR /users Y N Y N
PROJECT_ADMIN /projects Y Y Y Y
PROJECT_CREATOR /projects N N Y N
CONFIG_ADMIN /licenses Y NA Y NA
CONFIG_ADMIN /license/status Y NA NA NA
TASK_EDITOR /tasks NA Y Y Y
TASK_EDITOR /tasks/{ID}/owner NA Y NA NA

Permission Visibility and Access Breakdown

Permissions are refinery-wide and depending on the level of access, the visibility will vary for an individual user.

View the table below for the visibility and access differences among the available permissions.

Permission Name Visibility Access Breakdown Notes
USER_ADMIN View ALL Users ALL Access to Users Can Create, Update, or Delete Users; Assign Permissions
USER_CREATOR View ALL Users Can Create and View Users Can Create Users; Cannot Assign Permissions
PROJECT_ADMIN View ALL Projects ALL Access to Projects Can Create, Update, and Delete Projects; Assign or Delete UPRs
PROJECT_CREATOR Determined by UPR per Project Can Create Projects Can Create Projects and Assign UPRs During Initial Set-Up
CONFIG_ADMIN View Installed License and License Status Can Access the Currently Installed License Can Install Licenses
TASK_EDITOR View ALL Tasks ALL Access to Tasks Can Create Tasks; Update or Delete Tasks with Ownership; Take Ownership

A PROJECT_ADMIN can override any UPR in Data Refinery. Additionally, PROJECT_ADMIN and PROJECT_CREATOR permissions can make a GET request to the /users endpoint to retrieve basic information that can designate users to Projects and assign UPRs.

The combination of USER_ADMIN and PROJECT_ADMIN permissions grants the highest level of access throughout Data Refinery. A system-level user is maintained with this combination of permissions and it may be used to create additional users with the USER_ADMIN permission.

While users must have the TASK_EDITOR permission to create tasks, users also need ownership of a task to complete any updates or delete the task. To learn more about task ownership, see the Background Tasks page.

User Project Roles

User Project Roles (UPRs) filter what a user can see and do related to Projects. These UPRs are enforced on a per-Project basis.

Review the different UPRs in the table below.

UPR Endpoint GET PUT POST DELETE
Owner /projects Y Y N N
Analyst /projects Y N N N
Owner /sources Y Y Y N
Analyst /sources Y Y Y N

Note. Other UPRs may be added in future versions of Data Refinery.

UPR Visibility and Access Breakdown

As previously mentioned, UPRs are specifically related to Projects in Data Refinery. Users with assigned UPRs have access to those Projects, but the visibility and access varies with the UPR.

View the table below to see the access and visibility differences between UPRs in a Project.

UPR Visibility Access Breakdown Notes
Owner View Project, Users, and Sources Can Update Project. Can Query and Update Sources Can Assign UPRs or Transfer Ownership
Analyst View Assigned Projects and Sources Can Query  

To clarify, an individual user can be assigned multiple roles on a Project. An individual user can also be involved with multiple Projects at once.

Additionally, without holding certain Project permissions, users are limited to the Source actions in the User Project Roles table above. See the Source Permissions section to learn more about access to Sources through Permissions.

Default Permissions and Roles

When a user logs into Data Refinery for the first time, there are no default permissions given to the user. All permissions and roles must be assigned to a user when planning to work in Data Refinery.

Without any assigned permissions or roles, a user would log into Data Refinery, but see no Projects, Sources, Background Tasks, etc.

Managing UPRs

UPRs can be created, updated, and deleted when creating a Project via the POST API, or when updating a Project via the PUT API. UPRs cannot be assigned or updated via the User APIs.

Prerequisite: The target User already exists in the system. The User does not need any system-wide permission.

The following example payload can either be sent to the /api/projects POST or PUT endpoint. The only difference is that there would be no ID for the POST API (since a Project doesn’t have an ID until it is created in the system).

curl -X 'POST' \
  'https://dev.kingland-data-refinery-dev.com/api/projects' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_token_here' \
  -d '{
          "name": "tomtest1010",
          "userProjectRoles": [
             {
               "userID": "d62108d7-fca5-48b6-82da-2d621a95c715",
               "role": "analyst" 
             }
           ]
       }'

An example response can be viewed below.

{
  "ID": 5264,
  "name": "tomtest1010",
  "userProjectRoles": [
    {
      "ID": 28,
      "userID": "d62108d7-fca5-48b6-82da-2d621a95c715",
      "projectID": 5264,
      "projectRole": 1,
      "user": {
        "ID": "d62108d7-fca5-48b6-82da-2d621a95c715",
        "createdAt": "2023-09-26T23:40:27.958274Z",
        "updatedAt": "2023-09-26T23:40:29.349859Z",
        "deletedAt": null,
        "userName": "johnd",
        "email": "johdoe@example.com",
        "lastUpdatedDBPassword": "2023-09-26T23:40:29.349415Z",
        "permissions": null
      },
      // Some fields are omitted for brevity
    }
  ]
}

The APIs will update the UPRs for a Project to match what’s provided in the request. For a Project with existing UPRs, this means:

  • To add a UPR, append a new UPR to the UPR list.
  • To update a UPR, update the element within the UPR list.
  • To remove a UPR, remove the element from the UPR list.

For the role field, use the table from UPR Visibility and Access Breakdown to find the appropriate Role. Role names are case-insensitive in the API.

Error Messages & Troubleshooting

The following table explains common error messages and their interpretation to find a solution.

Error Message Interpretation Solution
“Every user must be assigned a valid role” Incorrect Role name See the table above for valid values, then retry the request
“You do not have permission to assign Project Owners” User who is not a PROJECT_ADMIN tried to add a Project Owner Get necessary permission first
“Failed to associate a user to a Project” – user not found (only viewable in API logs for security) The user does not exist in the system Create the new user

Source Permissions

Most users in Data Refinery will have access to the /sources endpoint, but access will be slightly different based on the Permissions and UPRs the user has.

View Source

All users who can view a Source can create new versions, upload data to the versions, and query the data uploaded to that Source.

Users can view the Source based on the combination of the Permissions and UPRs for the Projects they are members of:

  • PROJECT_ADMIN - Can view all Sources and their Project associations in Data Refinery.
  • PROJECT_CREATOR - Can view all Sources in Data Refinery, but only has access to Project associations by assigned UPRs.
  • Project Member (Owner and Analyst UPRs) - Can view Sources in Projects where they are a member. The Project associations in the response will include the Projects they have access to. Project members will lose access to a Source if it is removed from a Project, unless the users have other permissions granting them access.
  • USER_ADMIN and USER_CREATOR - Has no access through their permission unless they are added to a Project and assigned UPRs.
  • Users with no Permissions and no assigned Projects - Cannot view any Sources in Data Refinery.

Create Source

Any user in Data Refinery can create a Source.

Not all users can view the new Source if they do not have the required access to it (even if they created it). See View Source rules for more information. A PROJECT_ADMIN or a PROJECT_CREATOR might be needed to link those Sources to Projects.

Update Source

All users who can view the Source can update basic information in the Source like Description and Type.

Note. Project Associations: The Project associations to a Source can be added and removed using the /project/{ID}/associations endpoints.

Delete Source

Only a PROJECT_ADMIN can delete a Source in Data Refinery. The request to delete the Source will fail if the Source is associated with any active Projects.

Audit Permissions

Data Refinery has an audit logging system designed to enable governance, compliance, and auditing. The audit logging system can store and query for audit events, which are changes made to the system by a user. Specifically, the events track changes to Sources over time.

In order to query the audit log, users must have the AUDIT_READALL permission. This permission can be granted by a USER_ADMIN in the DR Designer. Refer to the Audit Logging page for more information.

Configuration Permissions

In order to work with Data Refinery licensing, a user must have the CONFIG_ADMIN permission. This permission can be granted by a USER_ADMIN and allows a user to update the license status of Data Refinery. To learn more, see the Installing a License page.

Copyright © 2025 Kingland Systems LLC