Authentication

Bearer Token

Summary

Oauth 2 based bearer tokens are the primary authentication mechanism for the API. These tokens are generated on a per profile basis.

Requesting a token

To obtain a new token, the consumer_key and consumer_secret - available in the profile configuration section of the Case app - are used for temporary authentication.

To authenticate using the consumer_key and consumer_secret the should be submitted as HTTP Basic Authentication. The example requests below demonstrate this:

Curl

$ curl \
    -XPOST \
    -u consumer_key:consumer_secret \
    http://api.staging.decisiv.net/platform_api/oauth2/token \
    -d 'grant_type=client_credentials' \
    -H 'Accept: application/xml'

Raw HTTP

POST /platform_api/oauth2/token HTTP/1.1
Host: api.staging.decisiv.net
User-Agent: Application Name
Authorization: Basic { auth_str }
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: ...
Accept-Encoding: gzip

grant_type=client_credentials

The successful response to the above requests will contain a bearer token for use in making further API requests. Use of the token is described in the next section.

XML

<?xml version="1.0" encoding="UTF-8"?>
<AuthorizationResponse xmlns="http://www.decisiv.net/platform_api/0.0.7/Case/AuthorizationResponse"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.decisiv.net/platform_api/0.0.7/Case/AuthorizationResponse">
    <token>NmIzMDI1NGUtYTVhMC0xMWU1LWJjODAtNDA2YzhmNGQ1ZmUwCg==</token>
    <type>Bearer</type>
</AuthorizationResponse>

Using a token to access resources

Bearer tokens are subitted in the Authorization header.

Given a token value of NmIzMDI1NGUtYTVhMC0xMWU1LWJjODAtNDA2YzhmNGQ1ZmUwCg== the header format would be as below:

Authorization: Bearer NmIzMDI1NGUtYTVhMC0xMWU1LWJjODAtNDA2YzhmNGQ1ZmUwCg==

The example requests below show this in more detail.

Curl

$ curl \
    -H 'Authorization: Bearer LLPmMJBrJV7OJgRfZMy44alqohy82kokVH56BYOLiE' \
    http://api.staging.decisiv.net/platform_api/bearer_test

Raw HTTP

GET /platform_api/bearer_test HTTP/1.1
Host: api.staging.decisiv.net
User-Agent: Application Name
Authorization: Bearer LLPmMJBrJV7OJgRfZMy44alqohy82kokVH56BYOLiE
Accept-Encoding: gzip

In the event that a Bearer token is used for an endpoint that doesn’t support it, a 403 Forbidden response will be returned.

HTTP/1.1 403 Forbidden

In the event that an invalid Bearer token is provided 401 Unauthorized response will indicate the the given credentials are invalid.

HTTP/1.1 401 Unauthorized