Authentication¶

Polarion REST API calls are authenticated via JSON Web Tokens (JWTs).

Every call is individually authenticated, there are no persistent sessions.

• Use Personal Access Tokens.

• Use the Polarion portal.

Authentication with PAT¶

When you try to access Polarion's REST API you must provide a Polarion Personal Access Token in the Authorization header of each request.

Authorization: Bearer {personal_access_token}

If the token is missing or invalid, a 401 Unauthorized response is returned.

Test REST Endpoints using the Swagger UI¶

To test the Polarion REST endpoints using the Swagger UI, click Authorize and authorize yourself using your Polarion Personal Access Token.

(Personal Access Tokens are already used for SOAP Web Services.)

• Any Polarion user can create and manage their own tokens.

• Polarion administrators can immediately revoke another user's tokens in an emergency.

• Personal Access Tokens can also be renewed.

  • Polarion users can renew their own (expired or valid) tokens.
  • Privileged users (with MANAGE USER permissions in the Global context) can also renew the expired/valid tokens of other users.
  • Administrators can set the number of days before a renewed token expires with the following property in the polarion.properties file: com.siemens.polarion.security.personalAccessToken.maxDaysBeforeRenewedTokenExpiry (The default value is 90 days.)

Authentication from Polarion without PAT¶

To access the Polarion REST API, you can issue an HTTP request using JavaScript while within an active Polarion session without having to generate a Personal Access Token (PAT).

To authenticate through the Polarion REST API, you can use the X-Polarion-Rest-Token header, which is bound to the authenticated session and follows the same lifecycle.

The generated X-Polarion-REST-Token is only valid for the current session and becomes invalid when you log out.

To use the X-Polarion-REST-Token, add the following property to the polarion.properties file:

com.siemens.polarion.rest.security.restApiToken.enabled=true

To authenticate your Polarion REST API call, supply the X-Polarion-REST-Token header in each Polarion REST API request.

The value of the header is obtained from the top.getRestApiToken() function, which generates the session-bound token.

The function is available in the Polarion UI and can be called directly using top.getRestApiToken(), window.getRestApiToken().

The getRestApiToken() function is available on:

• Live Report Pages (In the scripting widgets like "Script - Block".)

• Velocity and Java Widgets

• Classic Wiki Pages

• LiveDoc Documents (In the Wiki Content sections.)

• Any other place with direct access to Polarion's UI DOM where JavaScript can be executed.

The getRestApiToken() function is NOT available on:

• Work Item/Document Sidebars (JavaScript execution support is not yet implemented.)

• Workflow Scripts (Since there is no UI with a DOM to access the function.)

• Jobs (same as Scripts),

• Any other place where the Polarion UI is not directly accessible.

Here's an example of how to authenticate using the X-Polarion-REST-Token token:

<script>
  // Declaration
  function fetchRestAPI() {
    var fetchUrl = "/polarion/rest/v1/projects/drivepilot/workitems/DP-584";
    var restToken = top.getRestApiToken();

    fetch(fetchUrl, {
      headers: {
        'Accept': 'application/json',
        'X-Polarion-REST-Token': restToken
      }
    })
    .then(response => {
      console.log("fetchRestAPI response: ", response);
      if (!response.ok) {
        throw new Error(`HTTP error! Status: ${response.status}`);
      }
      return response.json();
    })
    .then(json => {
      console.log("fetchRestAPI json: ", json);
    });
  }

  // Invocation
  fetchRestAPI();
</script> 

The following example shows how to use the Polarion REST API to create a new test Work Item using the X-Polarion-REST-Token token.

When the script is used on a Classic Wiki Page (or in the Wiki Content section of a LiveDoc Document), you must apply special handling via {pre} tags.

If not, Polarion processes the xWiki syntax, which changes and breaks the JavaScript code.

## This script creates a new Work Item in the current project from Classic Wiki Page, 
Document page, LiveReport Pages & Work Item Velocity/Java Form Extensions   

{pre} 
<button onclick="createWorkItem()">Create Test Work Item</button> 
#set($projectId = "") 
#if($document.getProjectId() != "") 
#set($projectId = $document.getProjectId()) 
#elseif ($page.getProject() != "") 
#set($projectId = $page.getProject()) 
#elseif ($page.getReference().projectId() != "") 
#set($projectId = $page.getReference().projectId()) 
#elseif ($object.getContextId().getContextName() != "") 
#set($projectId = $object.getContextId().getContextName()) 
#end   

<script>
  function createWorkItem() {
    var jsProject = '$projectId';
    if (jsProject == "") {
      alert("Please Select Project to Create Work Item");
      return;
    }
    var restToken = top.getRestApiToken();
    var fetchUrl = '/polarion/rest/v1/projects/' + jsProject + '/workitems';

    fetch(fetchUrl, {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'X-Polarion-REST-Token': restToken,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        'data': [
          {
            'type': 'workitems',
            'attributes': {
              'description': {
                'type': 'text/html',
                'value': 'My Work Item Description'
              },
              'title': 'My Test Work Item Title',
              'type': 'task'
            }
          }
        ]
      })
    })
    .then(response => {
      console.log('createWorkItem() response: ', response);
      if (!response.ok) {
        alert('Status ' + response.status + ': HTTP error!');
      } else {
        alert('Status ' + response.status + ': Test Work Item successfully created.');
      }
      return response.json();
    });
  }
</script>
{/pre}