> ## 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

## 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`<br />`/accounts/{accountId}` |
| `transactions` | No        | `/accounts/{accountId}/transactions`     |
| `statements`   | No        | TBD                                      |

Endpoint: `GET /oauth2/v4/authorize`

<CodeGroup>
  ```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=
  ```
</CodeGroup>

## 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`

<CodeGroup>
  ```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"
  }
  ```
</CodeGroup>

## 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`

<CodeGroup>
  ```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
  ```
</CodeGroup>