Developer Sandbox

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 to try creating a Task in the Sandbox.

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

⚠️

Don't forget to also include the KMS Key Policy for these roles if your Bucket is encrypted.

Triggering Failures

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

Example

This POST body for Create Task will trigger the "QA Failure" failure mode as described in the table above:

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