Bearer Tokens

Overview

The Authentication API takes a set of user credentials as an input and returns a JSON Web Token (JWT). This token provides credentials to access the MGP APIs and services provisioned to your user account.

The API uses OAuth2 Password Flow (also called Password Grant) to exchange your username and password for an access token. You then provide this token in an HTTP header.

Many applications and libraries already support Password Flow. They accept your username and password and manage the bearer tokens on your behalf. Some examples:

• QGIS can use OAuth for WMS access to MGP Imagery.
• The Python SDK maxar-platform uses the requests-oauthlib package to manage OAuth authentication.

If you are using an application that supports Oauth, it is best to let the application manage authentication. It's simply not convenient to use API tools to fetch a bearer token and then provide them to the application.

If you are coding a solution, using an OAuth library is best practice. Writing your own code to do the password exchange is not complicated and only requires knowledge about making HTTP requests and this approach may work for lightweight applications.

A bearer token can access all MGP APIs. However, for programmatic use we recommend API keys for authentication with non-administrative APIs.

Getting a Bearer Token from the API

To get a token, make a POSTrequest to the following URL:

POST https://account.maxar.com/auth/realms/mds/protocol/openid-connect/token

Include the following required body parameters in your request:

Body Parameters

Parameter	Value
client_id	mgp
username	The email address associated with your MGP user account.
password	The password for your MGP user account.
grant_type	password

This example shows the token request in an API client.

Get Token Response

200 OK

{
    "access_token": "string of token",
    "expires_in": 7199,
    "refresh_expires_in": 43199 ,
    "refresh_token": "string of refresh token",
    "token_type": "Bearer",
    "id_token": "string of id token",
    "not-before-policy": 0,
    "session_state": "session state",
    "scope": "string of scope details"
}

Response fields

Field	Description
access_token	The token that grants access to MGP APIs and services.
expires_in	The amount of time the token is valid, shown in seconds.
refresh_expires_in	The amount of time the refresh_token is valid.
refresh_token	A string value that can be used to request a new token without re-sending user credentials.
token_type	The token type is "Bearer".
id_token	A token that caches user profile information.
not_before-policy	If a not_before_policy is pushed, it will invalidate previous tokens.
session_state	The ID for the session.
scope	Scopes included in the access token.

Refresh Token

The Response to the GetToken request includes a refresh_token property. The refresh token allows you to request a fresh bearer token without sending a username and password again. Use the "refresh token" value from the GetToken response to make this request. Refresh tokens have a lifespan of 12 hours.

For this request, the grant_type is refresh_token.

Parameter	Value
client_id	mgp
grant_type	refresh_token
refresh_token	refresh_token string from the token response

This example shows a Refresh Token request in an API client:

A Refresh Token request returns the same response as a Get a Token request. You can also get a fresh bearer token by making another request to the token endpoint, providing a username and password.

Using a Bearer Token

The bearer token is found in the token response property access_token. Pass this string in your request headers as an Authorization header with the word "Bearer" and your access_token value:

Authorization: Bearer <token>

Bearer tokens are valid for two hours after creation.