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.
Sign in to MGP Pro
Select your initials in the lower left corner of the window to expand the profile menu and select "API Key" from the list.
- From the API key menu, select the "copy" button to copy your API key.
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 Parameter | Description | type | example |
---|---|---|---|
name | A name used to identify the key. For example, the name of your application. | string | "name": "beta-app" |
description | A description to identify the intended use of the key. | string | "description": "beta version of app-01" |
expiration_date | The 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:
Field | Description |
---|---|
id | The unique identifier for the API key string. |
name | The name assigned to the API key. If no name was provided, this field will not appear. |
description | Brief description of the API key's intended use. If no description was provided, this field will not appear. |
api_key | The API key. |
expiration_date | The date the API key will expire. |
last_modified_date | API keys cannot be modified. The last modified date will match the created date. |
created_date | The 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