Authenticating to the Black Diamond API

Authorization Overview

The Black Diamond API can use a “Resource Owner Password Credentials Grant” from the OAuth 2.0 specification for authentication and authorization. OAuth is an open standard which provides client applications with secure authorization to server resources. For more information on OAuth 2.0 and the resource owner password credentials grant, please refer to RFC6749 Section 4.3. The oAuth2 token is provided upon valid request along with a refresh token. The token must be provided with the API calls for authentication and data access purposes. Demonstration of the token is required in order to gain production level access to the API.

Required parameters:

  • Client ID - The client ID is an identifier that represents the client application accessing a server resource. This is similar to a person’s username but is at the integration partner level. This is the same for all API calls by a partner

  • Client Secret - Client Secret is similar to a password and should be treated as such. It is used to authenticate a client application at the partner level.

  • Black Diamond username – The username for a valid Black Diamond user. This identifies the client firm they are part of and what data they have access to. When testing, you can use the credentials you were given to access the testing firm at Black Diamond.

  • Black Diamond password - The credentials for the user. This should be discarded after initial use as the Refresh token detailed below can be used in its stead.

Response:

  • Access Token

  • Refresh token

Authorization Process Overview

Authorization Process – Password Workflow:

In order to obtain an access token, an authentication request has to be made to the Black Diamond Identity Server. One route to achieve this is using the username and password for a valid Black Diamond user. When successful the server will respond with a JSON response containing the access token.

  • POST to Black Diamond's OAuth URL: https://login.bdreporting.com/connect/token

    • The authentication POST request must be submitted using a Content-Type of “application/x-www-form-urlencoded”. The body of the request must contain the following key-pair values:

      • grant_type - The grant type is always set to “password”. This indicates to the server that the Resource Owner Password Credentials Grant is in use.

      • client_id

      • client_secret

      • username

      • password

  • Response – JSON response containing the access token & refresh token

    • The access token is valid for 10 minutes.

    • The refresh token returned in the response is valid for 14 days and can be used to generate a new access token after the access token expires

Authorization Process - Using a Refresh Token:

The lifetime of an access token is limited. The expiration time will be indicated in the response from the Black Diamond Authentication Server. Along with the expiration time, the response will contain a refresh token. Refresh tokens are credentials which should be used to retrieve future new access tokens, instead of storing & reusing the user’s username/password. For more information on refresh tokens, please refer to RFC6749 Section 1.5

  • POST to Black Diamond's OAuth URL: https://login.bdreporting.com/connect/token

    • The authentication POST request must be submitted using a Content-Type of “application/x-www-form-urlencoded”. The body of the request must contain the following key-pair values:

      • grant_type - The grant type is always set to “refresh_token”.

      • client_id

      • client_secret

      • refresh_token - This is obtained from the last authentication request where a refresh token was returned.

  • Response – JSON response containing the access token & refresh token

    • The access token is valid for 10 minutes.

    • The refresh token returned in the response is valid for 14 days and can be used to generate a new access token after the access token expires

    • **Important Note** When the refresh token is used to acquire a new access token, the call returns both an access token (valid for 10 minutes) and a brand new refresh token (valid for 14 days). You must store and use the new refresh token going forward as the original refresh token will expire when the new one is generated.

Retrieving Data from the API

Authenticating API Calls

After you have completed the above authorization workflow you can use the acquired access token and your subscription key from the developer portal to call any available Black Diamond API endpoint.  In each call to the API you will need to pass over two headers:

  • Bearer Token: The client must use the “Bearer” authentication scheme, in order to supply the access token. The “Bearer” authentication scheme consists of supplying the access token, prepended by the word “Bearer” and a space, as the authorization header’s value. Please refer to RFC6750 for further information on the authorization request header field.

  • Subscription Key: In addition to the Authorization header, each call must contain a header that passes your primary or secondary subscription key for your account on the Black Diamond developer portal.  This can be found in the “My Profile” page in the portal.  The format of the header must include “Ocp-Apim-Subscription-Key” as the key and your subscription key as the value.

Example Headers:

Example Headers

Making an API Call

  1. Authenticate to generate an access token using your client ID and Secret along with a valid Black Diamond username and password. Please reference the authentication section above for details.

  2. Using the access token generated in Step 1 and your subscription key, make an http post to the desired API endpoint with the appropriate parameters for the call included.

  3. The API will return the appropriate JSON response as detailed in the documentation.