Using OAuth 2.0

Starting with API v5, DigitalChalk uses OAuth 2.0 to authenticate API requests.  OAuth 2.0 is an open standard for authorization.

How It Works

Getting an Access Token

In order to make API v5 calls with DigitalChalk, you will need an access token.  This token can be retrieved through the DigitalChalk web application under the My Account -> API section.  (If you don’t see the API section, ask your Organization Administrator for API v5 permission).  This page will contain your API v5 access token.

Never share your token with anyone, and never use it in a program such that an end user can intercept it!

Your access token is registered to your DigitalChalk web application user.  You can use it to perform operations on the API with the same permissions you have in the DigitalChalk web application.

Using Your Access Token

Once you have your access token, you can use it to authorize requests to the API.  OAuth 2.0 access tokens act as “bearer tokens”, which means you are authorized due to the fact that you “bear” it.

As an example, let’s look at using the token on a sample request.  For this example, we will be using the Get Offerings request from API v5.

Let’s say you have retrieved your access token from the DigitalChalk web application and it is “token12345”.  To use it in the API request, you need to add the Authorization header to your request.

Request

GET /dc/api/v5/offerings HTTP/1.1
Host: api.digitalchalk.com
Content-Type: application/json
Authorization: Bearer token12345

As you can see on line 4 above, you need to add the “Authorization” header, with a value of “Bearer [your token]”.  This header is all that is necessary to use your access token.

Token Lifetime

DigitalChalk access tokens are extremely long-lived.  If your token ever expires, you can retrieve another one through the DigitalChalk web application under My Account.  If your token is ever compromised by a third-party, please contact DigitalChalk support as soon as possible so that we can re-issue a new access token for you (and terminate the compromised one).

The DigitalChalk system does not currently issue OAuth 2.0 refresh tokens.  To renew your token, you must go through the DigitalChalk web application interface.