Authentication

Carbon Engine uses the OAuth 2.0 protocol for authentication and authorization.

To begin, obtain OAuth 2.0 client credentials from Cogo. Then your client application requests an access token from the Cogo Authorization Server, extracts a token from the response, and sends the token with requests to Carbon Engine endpoints.

Obtain OAuth 2.0 credentials from Cogo

Cogo will supply you with a token endpoint, client ID, and client secret.

Obtain an access token from the Cogo Authorization Server

Make an HTTP POST request your unique token endpoint. Your token endpoint will look similar to https://auth.[env].[name].carbonengine.co/oauth2/token.

Authorization header

The client must pass their client_id and client_secret in the Authorization header using Basic HTTP authorization.

If you need to construct this header yourself, please review this documentation.

Content-Type header

The content-type header must be application/x-www-form-urlencoded. This is often the default in HTTP client libraries.

Request body

Only a single parameter is required, grant_type=client_credentials.

Example request

The example below demonstrates how to use your client credentials to obtain an access token with cURL:

curl --url https://auth.[env].[name].carbonengine.co/oauth2/token \
     --user client_id:client_secret \
     --data 'grant_type=client_credentials'

Example response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlBKRl8xRmFNcWVfcFoydDZPZUVWYyJ9.eyJpc3MiOiJodHRwczovL2NvZ28uZXUuYXV0aDAuY29tLyIsInN1YiI6ImFpMlFDR25IS3RwNlF5WVBkUTMwYXZ2UzF3QjJsNDBOQGNsaWVudHMiLCJhdWQiOiJodHRwczovL2FwaS5jb2dvLmNvIiwiaWF0IjoxNjEyNDEzOTk1LCJleHAiOjE2MTI1MDAzOTUsImF6cCI6ImFpMlFDR25IS3RwNlF5WVBkUTMwYXZ2UzF3QjJsNDBOIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.CwuFJ2h83-qSPDZuzxB9EA04m4blJvmiqDLJarTMW4q4Ac2j1t64bhmjcvwASGN48rgifVbUEn4H72s7BiULoSSMgMia3xIGdpaOxK7JGzNktG86cfSxJYJiRHWLBChPPkB5SF4SzWpT75_CIZTANuE9kcF69GplVi6o9pld_8LAGiOIGmO8I6RHCH-9qu9Y6LunbvEjLs78A8yYg1C_do8tnbf6oLMjUYe3mHNJRmdaOH0bMJN_vuu7dXX5BTN9TPnPG1Kk13JSGCp9P-dN98-O0RtMM0lPSNPu9kbf1El5xFHAWw8uVe1B9HpjlRf8wwcamwiWmSsmb5I_fwqkDQ",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Now that the application has an access_token, it is now able to make authorized calls to the API.

Using the access token to call API endpoints

You can use this bearer token with an Authorization Header in your request to obtain authorized access to the Carbon Engine API.

Every request must have an Authorization HTTP header with the access token, prefixed by the string "Bearer" and a space. For example:

Authorization: Bearer eyJhbGciO...wqkDQ

This example demonstrates using cURL to access the "categories" endpoint:

curl --url https://api.[env].[name].carbonengine.co/api/v2/categories \
     --header "Authorization: Bearer [insert-your-access-token]"

Please note that the API uses a different domain name than the authentication endpoint.

Requests which do not have a valid Authorization header will fail with a 403 HTTP status code.

Access tokens will expire after 1 hour. A new token can be requested using the process above.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.