Authentication via Client Credentials

Canopy supports the OAuth2 client credentials workflow for generating access tokens automatically. This workflow supports Canopy API usage in scripts and applications that do not require user interaction.

In order to configure your Canopy organization with a Machine to Machine Application, please login to Canopy and navigate to the Organization page then click the tab for "Authentication":

From this view, users are able to create a new set of Client Credentials. Users can also view, rotate, and delete the set of Client Credentials for their organization:

⚠️

The Client Credentials client_id and client_secret shown in Canopy are scoped to the organization. Each organization has one set of shared Client Credentials that any user can make changes to. Be very sure you know what you're doing if you choose to rotate or delete your organization's credentials.

Generating an Access Token

To generate an access token for use in Canopy API requests using your client_id and client_secret, make a request as follows:

curl --request POST \
     --url https://auth.canopy.umbra.space/oauth/token \
     --header 'content-type: application/json' \
     --data '{"client_id":"<YOUR_CLIENT_ID>","client_secret":"<YOUR_CLIENT_SECRET>","audience":"https://api.canopy.umbra.space", "grant_type":"client_credentials"}'

The response will contain your temporary access token in the access_token key:

{
  "access_token":"...",
  "expires_in":86400,
  "token_type":"Bearer"
}

Use the access_token in the response to make requests as described in Authentication.

Applications using this client credentials exchange to generate Access Tokens should cache the Access Token and reuse it until it expires. The Canopy API enforces a rate limit of ~50 client credentials exchanges per day.

⚠️

The Access Token is only valid for expires_in seconds. When it expires, the Canopy API will return a 401 Unauthorized error. Your application should gracefully handle these by requesting a new Access Token and retrying the request or by proactively updating the in-use Access Token just before it expires.

Rate Limiting

The access tokens that client applications retrieve via client credentials exchange should be cached by the application and be reused until they expire. Applications must not perform a client credentials exchange for a new access token every time they query the Canopy API.

To encourage this workflow, client credentials authentication requests are limited to 50 requests per rolling 24-hour period per client. JWTs returned from a successful authentication include the claims below to indicate the current usage status against the requesting application's quota.

📘

Rate Limit Response

Due to a limitation with our authentication provider, when the client credentials exchange rate limit has been reached, the request will return error code 400. To identify a rate limit error, the client must observe the 429 in response.error_description.code.

Example Response:

{
  "error": invalid_request,
  "error_description": {
    "code": 429,
    "message": "rate_limit",
    "rate_limit": 50, // defined rate limit for application
    "rate_limit_refresh": "2023-06-22T22:18:16.065Z" // time of next allowed client credentials exchange
  }
}

Developer Sandbox Credentials

To generate an Access Token for the Developer Sandbox:

curl --request POST \
     --url https://auth.canopy.umbra.space/oauth/token 
     --header 'content-type: application/json' 
     --data '{"client_id":"<YOUR_CLIENT_ID>","client_secret":"<YOUR_CLIENT_SECRET>","audience":"https://api.canopy.prod.umbra-sandbox.space", "grant_type":"client_credentials"}'

📘

This is the same request as for live tokens, with the audience switched to match the host name of the Sandbox API.