Authorization¶

REST operations require two sets of permissions:

• Permission to call the endpoints. (REST API Endpoint permissions.)
• Permission to perform specific operations on items. (Read, Create, Update, Delete.)

REST API Endpoint permissions¶

For REST API Endpoint permissions, the endpoints are categorized into:

• Global Endpoints: Endpoints where the project is not part of the path.

Example: PATCH /users/{userId}, GET /jobs/{jobId}

• Project Endpoints: Endpoints where the project is part of the path.

Example: GET /projects/{projectId}/workitems/{workItemId}/approvals

There are four REST API Endpoint permissions based on HTTP verbs:

GET, PATCH, POST, and DELETE.

For project-level endpoints, project-specific permissions can be set.

These permissions are set to true for the admin and project_admin roles in the Global context.

(And for all Projects by default.)

For all other roles, REST API Endpoint permissions are denied by default.

When an endpoint is called, REST API Endpoint permissions are checked.

To access GET /users/{userId}, GET permissions must be available for the calling user.

If the permissions are denied, the following error response is shown:

{

  "errors": [

    {

      "status": "403",

      "title": "Forbidden",

      "detail": "Sorry, you do not have the necessary permissions to perform this operation. 
      Please contact your Administrator if you need additional permissions.",

      "source": null

    }

  ]

}

To allow REST API access for all users for both the Global and Project contexts¶

(Should be applied when you do not want to restrict REST API access at all.)

Enable all REST API Endpoint permissions (GET, PATCH, POST, DELETE) for the everyone Role in the Global (Default repository) context.

Allow default REST API project-level access using project roles: (More restrictive)¶

Enable the following REST API Endpoint permissions in the global context:

• GET: project_user
• GET, PATCH, POST, DELETE: project_assignable, project_approver

It's important to remember that Polarion's REST API can be used externally by Polarion plugins and integrations and internally on LiveReport Pages.

• Restricting access to the REST API (even partially) can render REST API-based functionalities inoperable for some users.
• Administrators should first map out all the instances where the REST API is used and craft their REST API restrictions accordingly to avoid losing functionality.

Example that illustrates REST API Endpoint permissions and Polarion item level permissions:

Projects: project_A, project_B

User: user_A

Roles:

• project_admin in project_A (project_admin has GET/POST/PATCH/DELETE permissions)

• custom role with GET permissions in the Global context.

• project_user role in project_B. (project_user does not have any REST endpoint permissions.)

Endpoints:

1. GET/all/workitems

2. GET/projects/project_A/workitems

3. /projects/project_B/workitems

user_A:

• Can call endpoint (1) due to the custom role with the GET permission for the Global context.

• Can call endpoint (2) due to the project_admin role with GET/POST/PATCH/DELETE permissions for the Global context and these permissions are inherited (and not overridden at the project level) for project A.

• Can NOT call endpoint (3) because the project_user role has no required permission in the Project context.

Once the endpoint is called, Polarion permissions (Item-level) are checked, and a response is received based on the available permissions.

Polarion Resource-Based-Permissions (Item-level)¶

Most operations in this API require permissions. Polarion permissions are fully applied, so the calling user must have the necessary permissions for an operation to use it.

If the available permissions are insufficient, the 403 response is returned.

• Example Request:

  GET /polarion/rest/v1/projects/A

• Response Body:

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "You do not have permission to view Project 'A'."
    }
  ]
}