How to enumerate user permissions from API

Get Help
2

Hi @fedoras,

I was on vacation, apologies for the late reply.

In Specify 7, there are different tables that capture the complete picture of a particular user’s permissions:

Table Name Role
spuserpolicy Stores individual user policies (collection-scoped or global).
spuserrole Associates Specify users with roles.
sprole Defines roles at the collection and institution level (group of policies).
sprolepolicy Stores policies attached to each role (collection-scoped or global).

The Specify 6 permissions are set in the sppermission, spprincipal, and other tables. They do not affect the permissions a user has in Specify 7.

To build a comprehensive report of what a user can do, you’ll want to combine two sets of permissions: those applied directly to the user and those granted by the roles they belong to.

You can see the full list of permissions API endpoints here: Specify 7 Operations API

API endpoints
API endpoints2600×2238 425 KB

Step 1: Retrieve Direct User-Specific Policies

The API has an endpoint specifically for this. You’ll need the user’s ID and the collection ID you want to check against (can be obtained via a query or via another API request to the specifyuser and collection tables).

Make a GET request to this endpoint:

/permissions/user_policies/{collectionid}/{userid}/

For example, for user ID 12 in collection 4, the call would be /permissions/user_policies/4/12/.

The response will be a JSON object containing the list of permissions that user is explicitly allowed to perform on that resource. This shows you any permissions assigned directly to that user, separate from what is given to them by their roles (by default, most users will only have collection access):

{
	"/system/sp7/collection": ["access"]
}

Don’t forget that users can also have institution-level policies that apply across all collections. You can get those with a similar call, which would also reveal if the user is an Institution Admin (has all permissions) or not:

/permissions/user_policies/institution/{userid}/

Step 2: Retrieve Role-Based Policies

Next, you need to find out what roles the user has and what permissions those roles grant. This is a two-part lookup.

First, get the list of roles assigned to the user within that same collection by making a GET request to the user_roles endpoint:

/permissions/user_roles/{collectionid}/{userid}/

This will return an array of the user’s roles, each with an ID and a name.

[
    {
        "id": 1,
        "name": "Data Entry Clerk"
    },
    {
        "id": 5,
        "name": "Researcher"
    }
]

Second, for each role ID you get back, you’ll make another GET request to the role endpoint to see its specific policies:

/permissions/role/{roleid}/

For example, a call to /permissions/role/5/ for the “Researcher” role might return this:

{
  "id": 5,
  "name": "Researcher",
  "description": "Grants read, create and update access to all data tables. read only access to all tables.  Query builder and Record sets",
  "policies": {
    "/querybuilder/query": [
      "execute",
      "export_csv",
      "create_recordset",
      "export_kml"
    ],
    "/table/agent": [
      "read",
      "create",
      "update"
    ],
...

You can combine the user policies from Step 1 with the policies from all of their roles in Step 2 to create a complete list of that user’s permissions for the specified collection. If you do build a tool to effectively report this, please let us know as this has been a requested feature for other institutions as well: