Token-based Authentication

The REST API authentication mechanism is based on OAuth 2.0, an open protocol for secure authorization.
Each HTTP request must be authenticated with an access token, which is first obtained from the token endpoint.

Token Endpoint

The token endpoint is located alongside the OData endpoint:

http://<server>:5181/token

Obtaining a Token (Basic Authentication)

Send an HTTP POST request:

POST http://myserver:5181/token  HTTP/1.1
Content-Length: 247
Content-Type: : application/x-www-form-urlencoded


grant_type=password&username=<username>&password=<password>
  • Replace <username> and <password> with valid PROLIN Smart Suite credentials.
  • It is recommended to use integration accounts where possible.

Example Response

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 826
Content-Type: application/json;charset=UTF-8
Expires: -1
Access-Control-Allow-Origin: *
Date: Fri, 26 Apr 2019 08:30:57 GMT

{
    "access_token": "<token_value>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "304384a5beb5ac2dbb5718f2379043d8bf005b00d00023008c00f20050808dfe",
    ".issued": "Fri, 26 Apr 2019 08:30:53 GMT",
    ".expires": "Fri, 26 Apr 2019 09:30:53 GMT"
}
  • access_token: token used for requests.
  • expires_in: token lifetime (default: 3600 seconds).
  • refresh_token: allows refreshing access without credentials.

Using the Token

Include the token in the Authorization header:

Authorization: <token_type> <access_token>

Example:

GET http://myserver:5181/odata/Problems  HTTP/1.1
Authorization: Bearer AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAaOIjiF40-0a24-ttFR8_OwAAAAACAAAAAAAQZgAAAAEAACAAAABXxoPE6UwfxXPQ5g-rNm7L6THNZOWSJQaIqXKB7_lNiwAAAAAOgAAAAAIAACAAAADMYV4nHj7HSQCRUMxOsisZjH8jfKpbmqMoUde0laBUgAABAAC7woiceHdbCUXFHiLJXilEEKRf-owezmc4gJlqLEXLR5Vp03SDcVYmGSDaHxgKfU74EDTaDsaTiZDoYzkEHUmcKH5aGBSu3XPHO2yezvRxJidQv50vE6BDx9YclMWfIfoF76pu78kIBSdHC4HozWBtLFvSJqu89zMHNNO3f-dMikCDQghr6mniWJxE1Iwueq4IEJbRchEqyCtmJqGHSejJ88LF8yOARR4wUrOhtlDjXWyqM1c9D6DUgAhdoT5mhO4a0I8bwZOWFpKFs9pdJWTMwlPuTysD936MVDAZkfy6SCiYlHOBaOrb_wLFosXcacU_UfV2Kg-2OnRtVgtXdTu1QAAAAKVZBpQ98vojwX2vcggoWL9srdWd8XJ9kToSLB0Lo6j-HGQhtl2_hJZYNoUa_N2q1oQp7qqmJn9Js_QQ_DTaBo0

Refreshing Tokens

Tokens expire after 3600 seconds. Use the refresh token to obtain a new one:

POST http://myserver:5181/token  HTTP/1.1
Content-Length: 75
Content-Type: : application/x-www-form-urlencoded


grant_type=refresh_token&refresh_token=304384a5beb5ac2dbb5718f2379043d8bf005b00d00023008c00f20050808dfe
  • Refresh tokens are valid for 7 days.
  • Each refresh token can be used only once.
  • Tokens are tied to the client machine and cannot be transferred.
  • Refresh tokens remain valid even if the server/module is restarted.

Ending Sessions

  • A session is created upon first use of an access token.
  • Sessions follow the same rules as normal application sessions (timeouts, expiration).
  • Too many short-lived sessions may hit the maximum number of concurrent users.

To explicitly end a session:

POST http://myserver:5181/connect/endsession  HTTP/1.1


Authorization: Bearer <BEARER_TOKEN>
  • Replace <BEARER_TOKEN> with the actual token.
  • Recommended after completing a unit of work or batch tasks.
Back to top