Authentication¶

The calls of the Polarion REST API are authenticated via JSON Web Tokens. Every call is individually authenticated, there are no persistent sessions.

Currently, the only supported method to authenticate and access the Polarion REST API is using Polarion personal Access Tokens. The personal Access Token is an existing feature. For example, it is already used for SOAP Web Services.

Any Polarion user can create and manage their tokens. Polarion administrators can immediately revoke individual tokens in an emergency.

The Personal Access Tokens can also be renewed. Privileged users (those with Manage User permissions in the global context) can renew the expired tokens of other users in addition to themselves, and non-privileged users can renew expired/non-expired tokens for themselves.

The number of days before the renewed token expires is configured in the following property:

com.siemens.polarion.security.personalAccessToken.maxDaysBeforeRenewedTokenExpiry

The default value is 90 days.

For more information on how to generate or revoke a personal Access Token in the Polarion UI, see Access Token support.

Authorization Header¶

Provide a Polarion personal Access Token in the Authorization header of each request if you try to access Polarion REST API with any technology:

Authorization: Bearer {personal_access_token}

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

The API reference documentation in SDK has further examples on how to provide the authentication token using the command line or different scripting languages.

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

REST API access 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). This means you can fetch data from the API without needing a 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. (This means you don't need to supply a PAT when making API calls.)

The generated X-Polarion-REST-Token is only valid for the current session and becomes invalid once the user logs 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.

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

<script>

// declaration
function fetchRestAPI(resource, options) {   
    var restToken = top.getRestApiToken()
    if (options == undefined) {
        options = {};
    }
    if (options.headers == undefined) {
        options.headers = new Headers();
    }
    if (options.headers instanceof Headers) {
        options.headers.set("X-Polarion-REST-Token", restToken); 
        options.headers.set("Accept", "application/json");  
    } else {
        options.headers["X-Polarion-REST-Token"] = restToken; 
        options.headers["Accept"] = "application/json";
    }
    return fetch(resource, options);
}

// invocation
fetchRestAPI("/polarion/rest/v1/projects/drivepilot/workitems/DP-584")
      .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);
      });

</script> 

Community

Connect and Collaborate with Industrial Professionals and Join the Community!