OAuth Authentication

Overview

Decisiv is transitioning to API authentication leveraging the industry standard OAuth 2.0. By doing so, we will be able to offer consumers a more familiar and openly supported interface.

In order to help our existing consumers transition to this new standard, we are exposing and requiring the usage of the X-DECISIV-TRANSITON-TOKEN HTTP Header which will properly scope requests during this transition.

The following diagram captures the new flow for interacting with the Decisiv APIs.

decisiv-api-authentication-oath-flow

Setup

OAuth Application

Each API consumer will own and maintain one or more OAuth Applications which will be used as an identifying source when utilizing the new OAuth flow.

This application will consist of managed client_id and client_secret value which consumers should keep secured.

Transition Token

Decisiv offers a self service method of retrieval for interested consumers who have access to the Case application. The Transition Token can be generated (and later accessed) by navigating to:

Admin > Customize Your Database > Platform API

New consumers should click the Create Transition Token button. Existing locations with a previously generated token will see the Transition Token listed in a table under the Transition to OAuth announcement.

Requesting a Token

Once you have an Application registered in the Decisiv ecosystem, you may request an access_token from our Authentication server.

NOTE: At this time, all API consumers will need to utilize the Password flow for authentication. This can be initiated by setting the grant_type attribute to password as shown in the example below.

Request

curl -X POST \
  https://login.staging.decisivapps.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
      "client_id":"DECISIV_SUPPLIED_CLIENT_ID",
      "client_secret":"PROTECT_THIS_SECRET",
      "grant_type":   "password",
      "username": "decisiv-api-example",
      "password": "SECURE_PASSWORD_HERE"
    }'

Response

{
  "access_token":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN_VALUE_HERE",
  "created_at": 1563275159
}

The access_token returned in the response will be valid for accessing supported Decisiv APIs. Please note the expiration of the token which is noted by the expires_in attribute (and also available inside of the access_token). Please note, expires_in is represented in seconds.

You may wish to leverage an OAuth client for managing token expiration or implement a process using the refresh_token.

Using a Token

The OAuth flow is currently supported in both the Platform API as well as the Service Events API.

Requests will require the following HTTP Headers:

Authorization
X-DECISIV-TRANSITION-TOKEN

Request

curl -X GET \
  https://api.staging.decisivapps.com/platform_api/cases \
  -H 'Accept: text=xml;version=0.3-beta' \
  -H 'Accept-Version: 1' \
  -H 'Authorization: Bearer ACCESS_TOKEN_GOES_HERE' \
  -H 'X-DECISIV-TRANSITION-TOKEN: TRANSITION_TOKEN_HERE'