Skip to main content

Introduction

Getting Started​

Get started by reaching out to the Carbon Trail team at support@carbontrail.net to get an application provisioned for your organization.

Once an application is provisioned, the appropriate credentials will be sent to you via email. You can then use these credentials to access the API.

You will also be provided the unique organization ID for your organization in the Carbon Trail platform as that will be needed to access the API.

Authentication​

We recommend authenticating with an API key. API keys are simpler to set up and manage for most Partner API integrations.

Generate an API key in the Carbon Trail Portal, then include it in the Authorization header of each request:

Authorization: ApiKey ctk_v1_xxx

API keys can also be restricted to the specific permissions required by your integration.

Treat your API key like a password: keep it out of source control and rotate it if you believe it has been exposed.

OAuth 2.0 authentication​

OAuth 2.0 using the client_credentials grant type is also supported.

How to get a token​

To get a token, you will need to send a POST request to the /oauth/token endpoint with the following parameters:

  • grant_type: set to client_credentials
  • client_id: the client ID provided to you by the Carbon Trail team
  • client_secret: the client secret provided to you by the Carbon Trail team
  • audience: set to https://api.carbontrail.net/partner

For example, using curl:

curl -X POST \
  https://auth.carbontrail.net/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&audience=https://api.carbontrail.net/partner'

The response will contain the access token, which you can use to authenticate subsequent requests to the API.

By default, the application/client will be allowed access to all the APIs via the OAuth route. If you'd like to restrict access to specific APIs, let us know when you submit your request to our team and we can grant only the required appropriate permissions to the application.