---
updatedAt: 2025-09-22T13:10:42.000Z
agentTools:
  projectIndex: https://docs.canopy.umbra.space/llms.txt
---

# Developer Sandbox

`api.canopy.prod.umbra-sandbox.space`

The Canopy developer sandbox offers API users a convenient platform to develop integrations with increased rate limits, without generating billable Collects on the Umbra platform. By default, the developer sandbox is enabled for all accounts.

This dedicated sandbox environment simulates real data for all Canopy API endpoints, maintaining a clear separation from the live environment. Generally, fields such as `satelliteID` will contain realistic values.

> 📘 Sandbox Data Separation
>
> The live and sandbox environments are entirely isolated from one another. Objects created in either environment can only be queried using an Access Token valid for the same environment.

***

## Using the Sandbox

The Sandbox API is accessible at `api.canopy.prod.umbra-sandbox.space`. To query the Sandbox instead of the live environment, replace `api.canopy.umbra.space` in your API queries with `api.canopy.prod.umbra-sandbox.space`.

In addition, you'll need a different Access Token. To retrieve your temporary Sandbox Access Token from the Canopy app, go to <https://canopy.umbra.space/account>, enable the "Test Mode" toggle in the app header, and copy the Access Token displayed while the "Test Mode" toggle is active.

Once you have an Access Token, you can follow the [Task Lifecycle Tutorial](https://docs.canopy.umbra.space/docs/task-lifecycle-tutorial) to try creating a Task in the Sandbox.

<Image align="center" className="border" border={true} src="https://files.readme.io/23262b2-small-Screenshot_2023-05-03_at_9.36.05_AM.png" />

***

## Task Lifecycle

For live Tasks and Collects, the `status` field provides users information about the current state of the Task and Collect. When Tasks are created in the live system, the [status transitions](https://docs.canopy.umbra.space/docs/tasking#task-status) as major lifecycle events take place, such as scheduling, collection, downlinking, processing, and delivery.

In the developer sandbox, these status changes and transitions are mocked as follows:

* After a new Task is created, the status transitions every few seconds from `RECEIVED` through to `SCHEDULED`.
* Once the Task is `SCHEDULED` the associated Collect(s) are created with status `SCHEDULED`.
* Within a minute after the `Task.windowEndAt` passes, the status for each Collect associated with the Task will rapidly transition every few seconds from `SCHEDULED` through to `PROCESSED`.
  * As in the live system, as the underlying Collect status transitions, the associated Task status will transition accordingly based on the Task `imagingMode`.
* As each `Collect` is marked `PROCESSED`, any normal post-processing operations will occur, including delivery of fake data associated with the Collect.
* Just like in the live system, Collects and their associated Tasks are marked `DELIVERED` when:
  * If the Task has a DeliveryConfig set, when the copy operation associated with that DeliveryConfig is complete.
  * If the Task has no DeliveryConfig, when the data is available for download in Canopy.

### Feasibilities

There are some functional differences between Feasibilities and Opportunities in the Sandbox vs the live system.

* Opportunities returned for a given Feasibility request are static, and do not necessarily represent the parameters sent on the Feasibility request. For example, the `windowStartAt` and `windowEndAt` on an Opportunity may not match the same window in the parent Feasibility's SpotlightConstraints.
* Feasibility results are generally returned much more quickly (<1s) than in the live system. Ensure your application treats retrieving Opportunities for Feasibility as an asynchronous operation.

***

## Data Delivery

All [DeliveryConfig](https://docs.canopy.umbra.space/reference/deliveryconfig) operations are supported in the sandbox. Users can create DeliveryConfigs and add them to their Tasks, and fake data will be delivered just like in the live environment.

### S3\_UMBRA\_ROLE Configuration

To support testing data delivery via this DeliveryConfig type, you'll need to allow additional role(s) to your Bucket Policy as described here: <https://docs.canopy.umbra.space/docs/delivery-configs#apply-s3-bucket-policy>

* Sandbox ARN, AWS commercial: `arn:aws:iam::922714215458:role/prod-prod-sbx-s3-external-delivery`
* Sandbox ARN, AWS GovCloud: `arn:aws-us-gov:iam::537355544329:role/prod-gov-prod-sbx-sar-data-delivery-cross-account-role`

<Callout icon="⚠️" theme="warn">
  Don't forget to also include the [KMS Key Policy](https://docs.canopy.umbra.space/docs/delivery-configs#apply-kms-policy-for-encrypted-buckets) for these roles if your Bucket is encrypted.
</Callout>

***

## Triggering Failures

Sandbox Tasks support triggering specific failures by including a specific string anywhere in the submitted `taskName` field when POSTing new Tasks.

| Failure    | String for taskName         | Description                                                                                                         |
| :--------- | :-------------------------- | :------------------------------------------------------------------------------------------------------------------ |
| QA Failure | `umbra:delivery:qa:failure` | Collect behaves as if Umbra's automated QA failed. See [Automated QA](https://docs.canopy.umbra.space/docs/automated-qa) for additional information. |

### Example

This POST body for [Create Task](https://docs.canopy.umbra.space/reference/create_task) will trigger the "QA Failure" failure mode as described in the table above:

```json
{
  {
  "imagingMode": "SPOTLIGHT",
  "taskName": "Test umbra:delivery:qa:failure",
  "windowStartAt": "2023-12-25T18:00:00+00:00",
  "windowEndAt": "2023-12-26T00:00:00+00:00",
  "spotlightConstraints": {
    "geometry": {
      "type": "Point",
      "coordinates": [-119.7027, 34.4221]
    }
  }
}
```