# Bearer Tokens

## Overview[​](#overview "Direct link to 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 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 imagery.
* **The Python SDK** `maxar-platform` uses the [`requests-oauthlib`](https://github.com/requests/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 platform APIs. However, for programmatic use we recommend API keys for authentication with non-administrative APIs.

## Getting a Bearer Token from the API[​](#getting-a-bearer-token-from-the-api "Direct link to Getting a Bearer Token from the API")

To get a token, make a `POST`request to the following URL:

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

```

Include the following required body parameters in your request:

### Body Parameters[​](#body-parameters "Direct link to Body Parameters")

| Parameter   | Value                                                |
| ----------- | ---------------------------------------------------- |
| client\_id  | mgp                                                  |
| username    | The email address associated with your user account. |
| password    | The password for your user account.                  |
| grant\_type | password                                             |

This example shows the token request in an API client.

![API token request](/assets/images/auth-get-token-6618e0e520cbf555b0eacbcb68ef829b.jpg)

## Get Token Response[​](#get-token-response "Direct link to Get Token Response")

200 OK

```json
{
    "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[​](#response-fields "Direct link to Response fields")

| Field                | Description                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------- |
| access\_token        | The token that grants access to 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[​](#refresh-token "Direct link to 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:

![authentication refresh token](/assets/images/auth-refresh-token-1603267e708a1da3e918f11eff1af789.jpg)

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[​](#using-a-bearer-token "Direct link to 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.