Web API: Token: Difference between revisions

From QPR ProcessAnalyzer Wiki
Jump to navigation Jump to search
m (Ollvihe moved page Web API: Login to Web API: Token without leaving a redirect)
No edit summary
 
(26 intermediate revisions by the same user not shown)
Line 1: Line 1:
The Web API session starts with a login. Session id is get as a response which is used to authenticate other Web API operations.
''Token'' operation logins a user, either using the username and password, or as part of the [[SAML_2.0_Federated_Authentication|SAML 2.0 authentication]] using the previously fetched ''samlhash''. An ''access token'' is returned as a response, which is used to identify the session in the following Web API interactions.


==Request==
The token request is following:
* Request url has the following form: <nowiki>https://SERVER/qprpa/token</nowiki>, where SERVER is the DNS name of the server. Note that the path doesn't contain '''api''' unlike all other operations in the Web API.
<pre>
* Request method is '''POST'''.
Url: POST qprpa/token
* '''Content-Type''' in the HTTP request header must be '''application/x-www-form-urlencoded'''.
Content-Type: application/x-www-form-urlencoded
* Payload contains the following parameters as url encoded:
Body (form data with username, password and grant_type fields):
** '''username''': Username.
username=myUserName&password=myPassword&grant_type=password
** '''password''': User password.
</pre>
** '''grant_type''': '''password''' (always use that value)


Example:
When using SAML 2.0 authentication, instead of the password, the url needs to have a ''samlhash'' parameter (value for it has been received earlier using [[Web_API:_saml2/acs|/qprpa/saml2/acs]]):
<pre>
<pre>
username=myUserName&password=myPassword&grant_type=password
Url: POST qprpa/token?samlHash=<samlhash>
</pre>
</pre>


==Response==
Note that the path doesn't contain ''api'', unlike other operations in the Web API. Example url: <nowiki>https://customer.onqpr.com/qprpa/token</nowiki>.
The response is a JSON object with several properties. One of them is '''access_token''' containing the session id.
 
Request body contains the following parameters (encoded with x-www-form-urlencoded):
* '''username''': Login name of the user
* '''password''': User password (empty in SAML 2.0 authentication)
* '''grant_type''': use always text "password"
 
The response contains the following fields:
* '''access_token''': contains the access token (session id).
* '''globalPermissions''': [[Roles_and_Permissions#Mapping_Roles_and_Permissions|Global permissions]] of the user as comma separated list.
* '''serverVersion''': Version of the QPR ProcessAnalyzer server.
* '''token_type''': contains always "bearer"
* '''userSettings''': All user-specific settings in stringified JSON format. Contains the following settings:
** '''uiLanguage''': UI language of the user.
** '''dateFormat''': The date time format used to present dates.
** '''firstDayOfWeek''': The first day of the week shown in e.g. calendars. 0 is Sunday and 1 is Monday.
** '''use12HourClock''': Whether the 12-hour clock is used when presenting time information.


[[Category: QPR ProcessAnalyzer]]
[[Category: QPR ProcessAnalyzer]]

Latest revision as of 17:36, 5 March 2023

Token operation logins a user, either using the username and password, or as part of the SAML 2.0 authentication using the previously fetched samlhash. An access token is returned as a response, which is used to identify the session in the following Web API interactions.

The token request is following:

Url: POST qprpa/token
Content-Type: application/x-www-form-urlencoded
Body (form data with username, password and grant_type fields):
username=myUserName&password=myPassword&grant_type=password

When using SAML 2.0 authentication, instead of the password, the url needs to have a samlhash parameter (value for it has been received earlier using /qprpa/saml2/acs):

Url: POST qprpa/token?samlHash=<samlhash>

Note that the path doesn't contain api, unlike other operations in the Web API. Example url: https://customer.onqpr.com/qprpa/token.

Request body contains the following parameters (encoded with x-www-form-urlencoded):

  • username: Login name of the user
  • password: User password (empty in SAML 2.0 authentication)
  • grant_type: use always text "password"

The response contains the following fields:

  • access_token: contains the access token (session id).
  • globalPermissions: Global permissions of the user as comma separated list.
  • serverVersion: Version of the QPR ProcessAnalyzer server.
  • token_type: contains always "bearer"
  • userSettings: All user-specific settings in stringified JSON format. Contains the following settings:
    • uiLanguage: UI language of the user.
    • dateFormat: The date time format used to present dates.
    • firstDayOfWeek: The first day of the week shown in e.g. calendars. 0 is Sunday and 1 is Monday.
    • use12HourClock: Whether the 12-hour clock is used when presenting time information.