---
updatedAt: 2025-09-24T20:37:02.000Z
agentTools:
  projectIndex: https://docs.canopy.umbra.space/llms.txt
---

# 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.

<ImageCard
  data={[
    {
      img: "https://files.readme.io/e5921e3-Screenshot_2023-06-15_at_11.57.48_AM.png",
 
			alt:"client credentials view screenshot",
    },

  ]}
/>

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

<ImageCard
  data={[
    {
      img: "https://files.readme.io/1a78fd5-Screenshot_2023-06-15_at_12.06.06_PM.png",

      alt: "Screenshot showing the Organization page with Client Credentials section.",
    },
  ]}
/>

<Callout icon="⚠️" theme="warn">
  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.
</Callout>

***

## 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:

```json
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:

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

***

## Using the Token

<Callout icon="ℹ️" theme="info">
  This is the same usage as UI‑generated tokens — the only difference is how the token is obtained.
</Callout>

Include the access\_token in the Authorization header of your requests in the format:

```json
Authorization: Bearer <access_token
```

**Example request to the Search Items endpoint:**

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

**Example response (truncated):**

```json
{
  "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
  ]
}
```

<Callout icon="⚠️" theme="warn">
  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.
</Callout>

***

## 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:

| Claim                                      | Type  | Description                                                                             |
| :----------------------------------------- | :---- | :-------------------------------------------------------------------------------------- |
| `https://umbra.space/rate_limit`           | *int* | The rate limit per 24-hour period configured or the authenticated client. (default: 50) |
| `https://umbra.space/rate_limit_remaining` | *int* | The number of auth requests remaining in the current interval (*rate\_limit - 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**:

```json
{
  "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](https://docs.canopy.umbra.space/docs/developer-sandbox):

```json
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"}'
```

<Callout icon="📘" theme="info">
  This is the same request as for live tokens, with the `audience` switched to match the host name of the Sandbox API.
</Callout>

***

ℹ️ For manual tokens, see [Authenticate via a UI‑Generated Access Token](https://docs.canopy.umbra.space/docs/authentication#/).