Connect to our APIs using OAuth2

This document describes all steps involved to connect to our APIs using OAuth2.

Prerequisites

Connecting to the API requires:

User assigned to product
After creating a new user account, the user must be assigned manually to the applicable API product(s).

Please contact CFP Greenbuildings to get assigned to your product(s).

The subscription key
After the subscription has been approved, customers can find the subscription key in the Developer Portal on the active subscription. This key is used to monitor usage of the API (rate limiting, request thresholds, etc). A separate key should be used for the TST and PRD endpoint.

The OAuth clientId & client secret
The clientId and client secret is provided by CFP Greenbuildings. This key pair is used for authentication and authorization. A separate clientId / secret pair is used for the TST and PRD endpoint.

The correct scope identifier per environment
Every environment (TST / PRD) has its unique scope identifier:
TST = 6a60518d-284c-459d-a824-4699b3376ba9/.default
PRD = 0be32ae2-0fa6-4239-ada6-8c9d2f2f3a2f/.default

Get an access token

Calls to our APIs require the usage of an access token. Using a valid clientId / secret to request an access token:

curl 'https://login.microsoftonline.com/53614885-877c-4d11-b9be-f099cbb02b0c/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<client_id>' \
--data-urlencode 'client_secret=<client_secret>' \
--data-urlencode 'scope=<environment_scope>/.default'

NB: copy the whole 'scope' value, including the '/.default'.

Call the API

Next, set the required 'Authorization' header, using the access token from the previous call. Also, set the required 'Ocp-Apim-Subscription-Key' header, so call can be monitored correctly.

curl 'https://api.cfpgreenbuildings.com/<customer>/version/api-endpoint?required-parameters=123abc' \
--header "Ocp-Apim-Subscription-Key: <subscription_key>" \
--header "Authorization: Bearer <access_token>"

NB: the exact endpoint URL plus parameters can be found in the API section of the Developer Portal.