Skip to main content

API Keys

Overview

An API Key is a compact, long-lived authentication method that can be used to access most MGP endpoints. This simplifies your code because the steps of fetching and refreshing your bearer token are not necessary. It can be passed either as a URL parameter or in an HTTP Header, which provides a wide range of compatibility with API clients.

All non-administrative MGP APIs accept an API key. API keys cannot be used with the Admin APIs. You cannot generate new API keys or use any other API key endpoints with an API key. Administrative endpoints require OAuth credentials instead.

API keys expire 180 days after creation by default. A shorter expiration date can be set when generating an API key, but it must be within 180 days of the creation date.

There is no limit to the number of API keys you can generate. An API key can be generated to authenticate a specific project. In some cases, in may be wise to create a specific key with a short lifespan.

Prerequisites

  • An MGP Pro account

Generating an API key

There are three ways to get an API key:

MGP Pro UI

You can access an API key from MGP Pro UI.

  1. Sign in to MGP Pro

  2. Select your initials in the lower left corner of the window to expand the profile menu and select "API Key" from the list.

MGP profile menu

  1. From the API key menu, select the "copy" button to copy your API key.

mgp profile menu

API Key Endpoint

To generate an API key by calling the API key endpoint, make the following request:

POST https://account.maxar.com/api-key/api/v2/api-key

You will need an Oauth2 bearer token to authenticate - see the Bearer Token guide.

Include these headers:

Content-Type: application/json
Accept: application/json
Authorization: Bearer <TOKEN>

Request body (optional)

A API key request can include a body with any of the following parameters:

Body ParameterDescriptiontypeexample
nameA name used to identify the key. For example, the name of your application.string"name": "beta-app"
descriptionA description to identify the intended use of the key.string"description": "beta version of app-01"
expiration_dateThe default expiration date is 180 days from the creation date. To set your own expiration date, include a date that meets the following requirements: does not exceed 180 days and must be in ISO 8601 datetime format. If no time zone information is provided, expiration times are assumed to be in UTC.string"expiration_date": "2024-01-30 10:30:00"
Example request body
{
"name": "beta-app",
"description": "beta version of app-01",
"expiration_date": "2024-01-30T00:00:00"
}

Response

The response includes the following details about your API key:

FieldDescription
idThe unique identifier for the API key string.
nameThe name assigned to the API key. If no name was provided, this field will not appear.
descriptionBrief description of the API key's intended use. If no description was provided, this field will not appear.
api_keyThe API key.
expiration_dateThe date the API key will expire.
last_modified_dateAPI keys cannot be modified. The last modified date will match the created date.
created_dateThe date and time the API key was generated.
Example response - Generate an API key
{
"id": "unique identifier for the API key",
"name": "api key name",
"description": "api key description",
"api_key": "api key string",
"expiration_date": "2024-01-30T00:00:00",
"last_modified_date": "2023-10-23T19:46:17.367682819Z",
"created_date": "2023-10-23T19:46:17.367681297Z"
}

Python SDK

maxar-platform has functions to manage keys. A basic example of making a new key is:

from maxar_platform.api_keys import generate_key
key = generate_key("my new key")
print(key['api_key'])

For more information see the module reference maxar_platform.api_keys

Invalidating API keys

API keys mirror the permissions for your account at the time the key was generated. The following changes will invalidate your API key:

  • The API key's expiration date is passed

  • Your account is deactivated

  • You delete the API key

If an invalid API key is used in a request, it will return a 401 Unauthorized response code.

Using your API key

  • As a URL Parameter: Add the parameter maxar_api_key equal to your API key.
  • As an HTTP Header: Send the HTTP header maxar-api-key with the API key as the header value with your request.

Example

This example shows a WFS Get Feature request with an API key parameter included.

GET https://api.maxar.com/streaming/v1/ogc/wfs?
&service=WFS
&version=2.0.0
&request=GetFeature
&typeNames=Maxar:FinishedFeature
&cql_filter=(acquisitionDate>='2019-01-01')
&maxar_api_key=<api key>

Retrieving a list of your API keys

To retrieve a list of all API keys for the account, make the following request:

GET https://account.maxar.com/api-key/api/v2/api-key

This will return a list view of your API keys and their associated data.

Example response - list all API keys
[
{
"id": "unique identifier for the API key",
"name": "api key name",
"description": "api key description",
"api_key": "the api key string",
"expiration_date": "2024-04-20 17:26:24",
"last_modified_date": "2023-10-23T17:26:24.660856Z",
"created_date": "2023-10-23T17:26:24.660856Z"
},
{
"id": "unique identifier for the API key",
"name": "api key name",
"description": "api key description",
"api_key": "the api key string",
"expiration_date": "2024-04-20 17:26:45",
"last_modified_date": "2023-10-23T17:26:45.246155Z",
"created_date": "2023-10-23T17:26:45.246155Z"
}
]

Deleting API keys

API keys can be deleted, which invalidates their access. You can delete a single ID or a list of IDs. Once an API key has been deleted, any further requests made with the deleted key will return a 401 Unauthorized response.

To delete an API key, make the following request with the 'id' in the URL path:

DELETE https://account.maxar.com/api-key/api/v2/api-key/id/{id}

To delete a list of API keys, place the following request:

DELETE https://account.maxar.com/api-key/api/v2/api-key

This requires a request body with an array of IDs.

{"ids": ["id1", "id2", "etc"]}

Success: 204 No Content