> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth

> Implement OAuth 2.0 for secure data access.

## Authorize

Specification: [https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1)

**Query Parameters**

| Name | Required? | Notes |
| - | - | - |
| `client_id` | Yes | --- |
| `redirect_uri` | Yes | --- |
| `response_type` | Yes | `code` is the only supported response type. |
| `code_challenge` | Yes | PKCE code challenge. Length must be greater than or equal to 32 characters. [https://datatracker.ietf.org/doc/html/rfc7636](https://datatracker.ietf.org/doc/html/rfc7636) |
| `code_challenge_method` | Yes | Must be set to `S256`. |
| `scope` | Yes | See scopes table. |
| `state` | No | An opaque value used by the client to maintain state between the request and callback. [https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-00#section-4.1.1.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-00#section-4.1.1.3) |

**Available Scopes**

| Name | Required? | FDX Resource Access |
| - | - | - |
| `openid` | Yes | Any |
| `customers` | No | `/customers/current` |
| `accounts` | No | `/accounts` `/accounts/{accountId}` |
| `transactions` | No | `/accounts/{accountId}/transactions` |
| `statements` | No | TBD |

Endpoint: `GET /oauth2/v4/authorize`

```shell Request theme={null}
curl -i -X GET 'https://base.url.com/oauth2/v4/authorize?client_id=8-NKBucVBblNc1LUlok76nz0-JpG8qWAXPIPf2P1NBA&redirect_uri=https%3A%2F%2Fcentzy.org%2Foidc_callback&response_type=code&code_challenge=uR7wSgfQ1JGJBevOjxefcyWnkX4SpclYyxorm10tBIY&code_challenge_method=S256&scope=openid+customers+accounts+transactions&state=YW55dGhpbmcgeW91IG5lZWQ='
  -H 'Accept: application/x-www-form-urlencoded'
```

```shell Response theme={null}
https://centzy.org/oidc_callback?code=SplxlOBeZQQYbYS6WxSbIA&state=YW55dGhpbmcgeW91IG5lZWQ=
```

## Access Token

Specification: [https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3)

Use this endpoint to get an access token or refresh token. This endpoint uses [`client_secret_basic` authorization](https://datatracker.ietf.org/doc/html/rfc7617).

All issued refresh tokens expire after 30 days. Refresh tokens are rotated upon use in the `refresh_token` flow with a new token in the response.

All issued tokens are opaque (reference tokens).

**Parameters**

| Name | Required? | Notes |
| - | - | - |
| `client_id` | Yes | ------ |
| `code` | Yes | The authorization code obtained from the [authorize](#oauth_authorize) endpoint. |
| `grant_type` | Yes | Only `authorization_code` and `refresh_token` grant types supported. |
| `redirect_uri` | Required if used with the authorize endpoint. | ------ |

Endpoint: `POST /oauth2/v4/token`

```shell Request theme={null}
curl -i -X POST "https://base.url.com/oauth2/v4/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic Y2xpZW50X2lkOnNlY3JldA==' \
  -d 'grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fcentzy.org%2Foidc_callback'
```

```json Response theme={null}
{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "example_parameter": "example_value",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "token_type": "example"
}
```

## Revoke Access Token

Specification: [https://datatracker.ietf.org/doc/html/rfc7009#section-2.1](https://datatracker.ietf.org/doc/html/rfc7009#section-2.1)

Use this endpoint to revoke an access token or refresh token.

**Parameters**

| Name | Required? | Notes |
| - | - | - |
| `token` | Yes | The token to be revoked. |
| `token_type_hint` | No | The type of token. Can be either `access_token` or `refresh_token`. |

Endpoint: `POST /oauth2/v4/revoke`

```shell Request theme={null}
curl -i -X POST 'https://base.url.com/oauth2/v4/revoke' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic Y2xpZW50X2lkOnNlY3JldA==' \
  -d 'token=SplxlOBeZQQYbYS6WxSbIA&token_type_hint=access_token'
```

```shell Response theme={null}
200 OK
```