Skip to main content

Authenticating to the Cirrus API

Authentication to the Cirrus API uses OAuth 2.0 bearer tokens. You will authenticate your calls to either the GraphQL or REST APIs by adding the bearer token to the Authorization header using the following format.

Authorization: Bearer [token]

OAuth 2.0 Resources and more information​

For more information on OAuth 2.0, we recommend the following resources

Retrieving a bearer token​

To receive a bearer token you will use one of the standard OAuth 2.0 grant types. Your contact will provide you with your OAuth 2.0 client information and information on which grant type(s) you will use.

Cirrus provides the following grant types to applications:

  • Authorization Code for user-facing applications such as native apps, web applications, Single-Page applications etc.
  • Client Credentials for applications without a user present, such as batch jobs or background processes.

See the sections below, or the OAuth 2.0 RFC for more details on these authorization grant types.

Authorization code grant​

To authenticate a user and receive an access token, you will redirect the user to the authorization endpoint.

Once the user has granted your application access to their data, they will be redirected back to your application. The redirect back to your application will contain a authorization code in the code query parameter.

https://my-nice-app.example.com/oauth-callback?code=bjbAVEp0BBQwgVibzPFyjAgKn

The authorization code can be exchanged for a access token by including it in a POST request to the token endpoint.

curl
  --user <your_client_id>:<your_client_secret>
  --location
  --request POST https://account.cirruscrm.io/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'grant_type=authorization_code&code=bjbAVEp0BBQwgVibzPFyjAgKn&redirect_uri=https%3A%2F%2Fmy-nice-app%2Eexample%2Ecom%2Foauth-callback'

If successful, you will receive a response similar to

{
  "access_token": "es3KCEYNXbnuO8IerZtzyh7cA",
  "token_type": "bearer",
  "expires_in": 3600
}

PKCE​

We recommend utilizing our Proof Code for Key Exchange to improve security in the authorization code flow. If you are building a native application, a single-page app, or any other application without a secure backend server able to store a client secret, you must implement PKCE in order to retrieve a token.

Client credentials grant​

To receive a access token, send a POST request to the OAuth 2.0 token endpoint. Send your client_id and client_secret as username and password in the Authorization header, formatted according to HTTP Basic Authentication.

curl
  --user <your_client_id>:<your_client_secret>
  --location
  --request POST https://account.cirruscrm.io/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'grant_type=client_credentials'

If successful, you will receive a response similar to

{
  "access_token": "es3KCEYNXbnuO8IerZtzyh7cA",
  "token_type": "bearer",
  "expires_in": 3600
}

Your token will be valid for the number of seconds specified in expires_in. You can at any time retrieve a new token by re-sending the POST request to the token endpoint.

Refreshing a bearer token​

If you have received a refresh token, you can retrieve a new access token, without requiring user input by performing a POST request to the token endpoint:

curl
  --user <your_client_id>:<your_client_secret>
  --location
  --request POST https://account.cirruscrm.io/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'grant_type=refresh_token&refresh_token=lRNnnd4p8kOlRobVy0v6D2UH6'

If successful, you will receive a new access token, with a new validity period in a response similar to the initial access token response. Note that you may receive a new refresh token in the response, and will have to use that one for future refresh token requests.

Retrieving user information from a token​

The Cirrus API provides a OAuth 2.0 Token Introspection endpoint. POST your access or refresh token to this endpoint to receive user and token information. Send your client_id and client_secret as username and password in the Authorization header, formatted according to HTTP Basic Authentication.

curl
  --user <your_client_id>:<your_client_secret>
  --location
  --request POST https://account.cirruscrm.io/oauth/token_info \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'token_type_hint=access_token&token=lRNnnd4p8kOlRobVy0v6D2UH6'

If the token is not active, or is invalid, you will receive a response with "active": false set.

{
  "active": false
}

If the token is valid, you will receive a response similar to

{
  "active": true,
  "id": "iPBvciIKIgAKZVZI",
  "token_type": "bearer",
  "userId": "3J82WWCsjktqwdzb",
  "cirrusUserId": "857",
  "cirrusCustomerId": "2375",
  "exp": 1638189611,
  "iat": 1635504011
}

Additional user information can be retrieved by querying the GraphQL viewer field. See the GraphQL documentation for more information on how to consume the GraphQL API.

Revoking tokens​

To revoke a access token, or a refresh token, send a POST request to the OAuth 2.0 token revocation endpoint. Send your client_id and client_secret as username and password in the Authorization header, formatted according to HTTP Basic Authentication.

curl
  --user <your_client_id>:<your_client_secret>
  --location
  --request POST https://account.cirruscrm.io/oauth/revoke \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'token_type_hint=access_token&token=lRNnnd4p8kOlRobVy0v6D2UH6'

When successful, you will receive a HTTP 200 status code and the token will be revoked.

OAuth 2.0 endpoints​

The Cirrus API exposes the following OAuth 2.0 endpoints

OAuth 2.0 authorization endpointhttps://account.cirruscrm.io/oauth/authorize
OAuth 2.0 token endpointhttps://account.cirruscrm.io/oauth/token
Token introspection endpointhttps://account.cirruscrm.io/oauth/token_info
Logout endpointhttps://account.cirruscrm.io/oauth/logout
Token revocation endpointhttps://account.cirruscrm.io/oauth/revoke

Client libraries​

It can be a bit tedious to manually make the requests, hence there's client libraries for virtually every platform. See the Code section on oauth.net for more libraries.

Node.js​

Python​

.NET​

Java​

Go​

PHP​