# API Keys ## Overview[​](#overview "Direct link to Overview") An API Key is a compact, long-lived authentication method that can be used to access most API 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 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](/docs/authentication/guides/get-a-token.md) 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[​](#prerequisites "Direct link to Prerequisites") * A Vantor Hub account ## Generating an API key[​](#generating-an-api-key "Direct link to Generating an API key") There are three ways to get an API key: * Through the Vantor Hub UI * [Sending a request to the API Key endpoint](#api-key-endpoint) * [Using the Python SDK](#python-sdk) ## Vantor Hub UI[​](#vantor-hub-ui "Direct link to Vantor Hub UI") You can access an API key from Vantor Hub UI. 1. Sign in to [Vantor Hub](https://pro.maxar.com/) 2. Select your initials in the top right corner of the window to expand the profile menu and select "API Key" from the list. ![Vantor Hub menu](/assets/images/api-key-profile-94e6a654701ac6ba7001ea970915a752.jpg) 3. From the API key menu, select the "copy" button to copy your API key. ![Vantor Hub menu](/assets/images/api-key-ui-bf612b947de3397c9d2b81ee3d50306a.png) ### API Key Endpoint[​](#api-key-endpoint "Direct link to API Key Endpoint") To generate an API key by calling the API key endpoint, make the following request: ```url POST https://account.maxar.com/api-key/api/v2/api-key ``` You will need an Oauth2 bearer token to authenticate - see the [Bearer Token](/docs/authentication/guides/get-a-token.md) guide. Include these headers: ```json Content-Type: application/json Accept: application/json Authorization: Bearer ``` #### Request body (optional)[​](#request-body-optional "Direct link to Request body (optional)") An 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 ```json { "name": "beta-app", "description": "beta version of app-01", "expiration_date": "2024-01-30T00:00:00" } ``` #### Response[​](#response "Direct link to 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 ```json { "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[​](#python-sdk "Direct link to Python SDK") `maxar-platform` has functions to manage keys. A basic example of making a new key is: ```python 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`](/docs/developer-tools/python-sdk/reference/api_keys.md) ## Invalidating API keys[​](#invalidating-api-keys "Direct link to 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[​](#using-your-api-key "Direct link to 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[​](#example "Direct link to Example") This example shows a WFS Get Feature request with an API key parameter included. ```bash 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= ``` ## Retrieving a list of your API keys[​](#retrieving-a-list-of-your-api-keys "Direct link to Retrieving a list of your API keys") To retrieve a list of all API keys for the account, make the following request: ```text 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 ```json [ { "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[​](#deleting-api-keys "Direct link to 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: ```text DELETE https://account.maxar.com/api-key/api/v2/api-key/id/{id} ``` To delete a list of API keys, place the following request: ```text DELETE https://account.maxar.com/api-key/api/v2/api-key ``` This requires a request body with an array of IDs. ```text {"ids": ["id1", "id2", "etc"]} ``` Success: `204 No Content`