# Request Token from Code

This endpoint allows you to exchange an authorization code for an OAuth 2 access token. Once you have an access token, you can make calls to our various other API Endpoints (like the [Accreditations API](https://developer.parallelmarkets.com/docs/1.x/server/accreditations-api)).

## HTTP Request

```http
POST https://api.parallelmarkets.com/v1/oauth/token
```

## Query Parameters

These parameters should be sent as URL encoded query parameters. See the [example using `curl`](https://developer.parallelmarkets.com/docs/1.x/server/token-api/#example) below.

| Parameter      | Description |
|----------------|-------------|
| `code`         | **Required.** The authorization code returned from Step 4 described [here](https://developer.parallelmarkets.com/docs/1.x/server/access-token#step-4-handle-the-oauth-20-server-response) |
| `client_id`    | **Required.** Displayed when you create a new OAuth Client in your business settings |
| `client_secret`| **Required.** Displayed when you create a new OAuth Client in your business settings |
| `redirect_uri` | **Required.** The same value as you provided in the authorize call in Step 2 described [here](https://developer.parallelmarkets.com/docs/1.x/server/access-token#step-2-send-user-to-authorization-url) |
| `grant_type`   | **Required.** As defined in the OAuth 2.0 specification this field must contain a value of `authorization_code` |

Note: Codes are single use

Make sure that you don't call this endpoint with the same parameters more than once (notably, with the same authorization `code` value). If the same `code` is seen in a subsequent request, all tokens (including the refresh token) initially issued for that code will be invalidated (per [the protocol guidelines](https://tools.ietf.org/html/rfc6749#section-4.1.2)).

## Response Parameters

| Parameter      | Description |
|----------------|-------------|
| `access_token` | The OAuth 2 access token. _This is all you need to now make requests to our other API endpoints._ |
| `token_type`   | This will always be `bearer` |
| `expires_in`   | The number of seconds until this token expires |
| `refresh_token`| A refresh token that can be used to get new access tokens. This will only be present if your client is authorized to receive refresh tokens. |
| `refresh_expires_in`| The number of seconds until refresh token expires |

## Token Expirations

Currently, tokens last for about a week and refresh tokens last for about 6 months. However, _this may change at any time without any prior notice_, so it is important to record the expiration returned (via the `expires_in` and `refresh_expires_in` parameters) along with the tokens. Expired tokens will not be accepted by the API.

## Example

Given an access code, request an OAuth 2 token.

```shell
curl -X POST "https://api.parallelmarkets.com/v1/oauth/token?code={code}&client_id={client_id}&client_secret={client_secret}&redirect_uri={redirect_uri}&grant_type={grant_type}"
```

The above command returns JSON structured like this:

```json
{
  "access_token": "MVXoULzTSdmDINFf",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "dmDINFfULzTSdMVXoU",
  "refresh_expires_in": 345600
}
```

# Refreshing a Token

This endpoint allows you to exchange an OAuth 2 refresh token for a brand new access token. Refresh tokens have much longer life spans and can be used to replace short-lived access tokens whenever necessary.

## HTTP Request

```http
POST https://api.parallelmarkets.com/v1/oauth/refresh
```

## Query Parameters

These parameters should be sent as URL encoded query parameters. See the [example using `curl`](https://developer.parallelmarkets.com/docs/1.x/server/token-api/#example-1) below.

| Parameter      | Description |
|----------------|-------------|
| `client_id`    | **Required.** Displayed when you create a new OAuth Client in your business settings |
| `client_secret`| **Required.** Displayed when you create a new OAuth Client in your business settings |
| `refresh_token`| **Required.** The refresh token provided in the result from the [original token request](https://developer.parallelmarkets.com/docs/1.x/server/token-api/#request-token-from-code) |
| `grant_type`   | **Required.** As defined in the OAuth 2.0 specification this field must contain a value of `refresh_token` |
| `scope`        | Optional. A space-delimited list of [scopes](https://developer.parallelmarkets.com/docs/1.x/server/scopes) for the token. If given, it must be a subset of the original scopes granted. |

Note: Refresh Tokens Are Single Use

You cannot use the same `refresh_token` more than once. Once used, all subsequent calls with the same token will fail with an HTTP `400` error.

## Response Parameters

| Parameter      | Description |
|----------------|-------------|
| `access_token` | The OAuth 2 access token |
| `token_type`   | This will always be `bearer` |
| `expires_in`   | The number of seconds until this token expires |
| `refresh_token`| A new refresh token that can be used to get new access tokens |
| `refresh_expires_in`| The number of seconds until refresh token expires |

## Example

Given an OAuth 2 refresh token, get a new authentication token.

```shell
curl -X POST "https://api.parallelmarkets.com/v1/oauth/refresh?client_id={client_id}&client_secret={client_secret}&refresh_token={refresh_token}&scope={scope}&grant_type={grant_type}"
```

The above command returns JSON structured like this: