Client Credentials

Setting Up 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.

To configure your organization with a Machine‑to‑Machine application:

1. Log in to Canopy.
2. Navigate to the Organization page.
3. Click the Authentication tab.
4. Create a new set of Client Credentials.

Users can also view, rotate, and delete the set of Client Credentials.

⚠️

Client credentials (client_id and client_secret) are scoped to your organization. Each organization has one shared set of credentials that any user can rotate or delete. Be careful when rotating or deleting credentials, as this will affect all users and applications.

Generating an Access Token

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

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"
}

Using the Token

ℹ️

This is the same usage as UI‑generated tokens — the only difference is how the token is obtained.

Include the access_token in the Authorization header of your requests in the format:

Authorization: Bearer <access_token

Example request to the Search Items endpoint:

curl --request GET \
  --url 'https://api.canopy.umbra.space/stac/search?limit=1' \
  --header 'Accept: application/geo+json' \
  --header 'Authorization: Bearer '

Example response (truncated):

{
  "type": "FeatureCollection",
  "context": {
    "limit": 1,
    "returned": 1
  },
  "features": [
    {
      "id": "<id>",
      "links": [
        {
          "rel": "collection",
          "type": "application/json",
          "href": "https://api.canopy.umbra.space/collections/<org>"
        }
        // ... additional links
      ],
      "assets": {},
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [18.61596485189158, -33.98736266276227, 0],
            [18.628773115767444, -33.952916395537784, 0]
            // ... additional coordinates
          ]
        ]
      },
      "collection": "<org>",
      "properties": {
        "created": "2022-06-03T19:12:23Z",
        "datetime": "2022-06-11T11:54:30Z",
        "platform": "<platform>",
        "umbra:status": "COMMANDED",
        "sar:instrument_mode": "SPOTLIGHT"
        // ... additional properties
      }
    }
  ],
  "links": [
    // ... pagination and navigation links
  ]
}

⚠️

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

To encourage caching, client credentials authentication requests are limited to 50 per rolling 24‑hour period per client.

• Applications should cache and reuse tokens until they expire.
• Do not request a new token for every API call.

JWTs returned from a successful authentication include claims to indicate usage:

📘

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.

ℹ️ For manual tokens, see Authenticate via a UI‑Generated Access Token.