FAIR Role API

Before using the API, ensure you are correctly setup to use the API (e.g. authentication) and have the appropriate permission to use the API. See the ‘FAIR API’ article for more information.

The FAIR Role API provides users with role management capabilities such as assigning Aridhia Managed roles to FAIR users, or creating new roles from the set of FAIR Permissions then assigning to users.

Prerequisites

In order to use the Role API, you need your FAIR user to have either:

  • the 'Admin' role assigned to your user.
  • a custom role with appropriate permissions such as role/create, role/assign, etc.

Caveats

  • Only one role can be assigned to a user at anytime.
  • Newly signed up users to FAIR who are not ‘approved’ into FAIR yet will not be able to access FAIR even if a role is assigned. Approving users is currently a step Aridhia can perform unless auto-approve and auto-assignment of roles is configured (upon request).
  • In order to assign a user to a role, you will need their user UUID. These can be provided by Aridhia or supplied by the user themselves via their browser development tools. In Chrome this is located at Menu -> More Tools -> Development Tools -> Network and search for /api/users and retrieve the UUID after /api/user.

Assigning a Role

In order to assign a role (either managed or custom) to one or many users, the following information needs to be obtained:

  • The code of the role (see the ‘Role-based Access Article’ or issue a GET request to the /roles endpoint to view codes of existing roles)
  • The user’s UUID that can be either be provided by Aridhia or by the user themselves via their browser development tools.

To assign a role, call the API with the following parameters:

  • Request type: PATCH
  • Endpoint: /roles/{code}/assign
  • Body: the body must include one or more user UUIDs. An example is below.

data json


{
    "users": \[
    {
    "uuid": "e6shs8-akq0q-mq0qnmvnxzpa"
    },
    {
    "uuid": "e7j01o-ama01-ms0qm0n9fhfo"
    }
    \]
}

Example API Call

Assigning two users to the ‘standard’ role (with the body above):

curl -X PATCH -d @data.json -H "Content-Type: application/json" -H "Authorization: Bearer ${TOKEN}" https://fair.aridhia.io/api/roles/standard/assign

Creating a Role

In order to create a role, the set of permissions to be included in the role must be decided. These can be found in the article ‘FAIR Permissions’. The request must contain the following information:

  • name: the user friendly name for the role
  • code: the code for the role (needed for assigning to users)
  • description: description for the role
  • permission: a list of permissions for the role.
  • category: the category of the permission (e.g. datasets, search, etc)
  • action: the CRUD action (e.g. create)

To create a role, call the API with the following parameters:

  • Request type: POST
  • Endpoint: /roles
  • Body: the body must include the information above. An example is below.

###data.json

{
    "role": {
    "name": "Example",
    "code": "example",
    "description": "A role for FAIR users"
    },
    "permissions": \[
    {
    "category": "datasets",
    "action": "read"
    },
    {
    "category": "datasets",
    "action": "create"
    }
    \]
}

Example API Call

Creating a role that only allows the creation and listing of datasets (with the body above):

 curl -X POST -d @data.json -H "Content-Type: application/json" -H "Authorization: Bearer ${TOKEN}" https://fair.aridhia.io/api/roles

Updating a Role

Roles can also be updated which takes the same arguments as creating a role as well as the code of the role to update. This will however replace all current permissions on the role with those specified in the request. To update a role, call the API with the following parameters:

  • Request type: PUT
  • Endpoint: /roles/{code}
  • Body: the body must include the information above. An example is below.

Example API Call

Updating the ‘data-steward’ role with the permissions listed above:

curl -X PUT -d @data.json -H "Content-Type: application/json" -H "Authorization: Bearer ${TOKEN}" https://fair.aridhia.io/api/roles/data-steward
Updated on June 28, 2023

Was this article helpful?