Authentication

Access Tokens

To use the Canopy API, you must send an access token in an Authorization header with each request.

Temporary Access Tokens

A temporary access token may be obtained from the Canopy account page.

Click on the copy icon to copy the access token to your clipboard, then use this token in all API calls as is demonstrated below. An access token expires 12 hours after generation, at which point a new one will need to be obtained.

Using an access token to make requests

When making API requests, provide the obtained access token in the Authorization header. This takes the form of Authorization: Bearer <access_token>. The token is valid for multiple requests, but expires after 24 hours.

In this example, we're querying the Search Items endpoint to retrieve one item:

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

{
  "type": "FeatureCollection",
  "context": {
    "limit": 1,
    "returned": 1
  },
  "features": [
    {
      "id": "<id>",
      "links": [
        {
          "rel": "collection",
          "type": "application/json",
          "href": "https://api.canopy.umbra.space/collections/<org>"
        },
        {
          "rel": "parent",
          "type": "application/json",
          "href": "https://api.canopy.umbra.space/collections/<org>"
        },
        {
          "rel": "root",
          "type": "application/json",
          "href": "https://api.canopy.umbra.space/"
        },
        {
          "rel": "self",
          "type": "application/geo+json",
          "href": "https://api.canopy.umbra.space/collections/<org>/items/<id>"
        }
      ],
      "assets": {},
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              18.61596485189158,
              -33.98736266276227,
              0
            ],
            [
              18.628773115767444,
              -33.952916395537784,
              0
            ],
            [
              18.58744233875694,
              -33.94224006466332,
              0
            ],
            [
              18.57461901358567,
              -33.97668208743458,
              0
            ],
            [
              18.61596485189158,
              -33.98736266276227,
              0
            ]
          ]
        ]
      },
      "collection": "<org>",
      "properties": {
        "created": "2022-06-03T19:12:23Z",
        "updated": "2022-06-04T12:34:02Z",
        "datetime": "2022-06-11T11:54:30Z",
        "platform": "<platform>",
        "umbra:ipr": 1,
        "umbra:status": "COMMANDED",
        "umbra:task_id": "<task_id>",
        "umbra:user_id": "<user_id>",
        "umbra:task_name": "<task_name>",
        "umbra:user_email": null,
        "umbra:vehicle_id": "<vehicle_id>",
        "sar:instrument_mode": "SPOTLIGHT",
        "umbra:status_history": [
          {
            "status": "SCHEDULED",
            "timestamp": "2022-06-03T19:12:23Z"
          },
          {
            "status": "COMMANDED",
            "timestamp": "2022-06-04T12:34:02Z"
          }
        ],
        "umbra:organization_id": "<org>",
        "umbra:auxiliary_properties": {}
      }
    }
  ],
  "links": [
    {
      "rel": "next",
      "type": "application/json",
      "method": "GET",
      "href": "https://api.canopy.umbra.space/search?limit=1&token=next:<token>"
    },
    {
      "rel": "root",
      "type": "application/json",
      "href": "https://api.canopy.umbra.space/"
    },
    {
      "rel": "self",
      "type": "application/json",
      "href": "https://api.canopy.umbra.space/search?limit=1"
    }
  ]
}

Using an access token on the API Reference page

The access token generated above may also be used to make requests on the API Reference page. Browse to any endpoint, such as Search Items, enter the access token under the Authentication section, and click "Try It!". Multiple languages are available for selection, and the code for making the request is available for copying.

The screenshot below demonstrates this interface. It indicates where to enter your access token and how to initiate the request: