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

# Dynamic Client Registration

> Implement Dynamic Client Registration for secure API access.

This API supports the automated onboarding for data recipient applications, called Dynamic Client Registration (DCR). It follows OAuth specification RFC7951 with some limitations and other minor enhancements. A special DCR token will be issued upon initial data recipient approval. This token must be passed in the authorization header: `Authorization: Bearer ${DCR token}`

DCR requests must originate from a whitelisted IP address configured during the onboarding process.

**Available Endpoints**

| Endpoint | Description |
| - | - |
| [`POST /oauth2/v4/register`](#dcr_create_client) | Creates and returns a new client. |
| [`GET /oauth2/v4/register/${client_id}`](#dcr_read_client) | Returns information about the specified client. |
| [`PUT /oauth2/v4/register/${client_id}`](#dcr_update_client) | Updates and returns information about the specified client. |
| [`DELETE /oauth2/v4/register/${client_id}`](#dcr_delete_client) | Deletes the specified client. |

## Client Response Fields

| Field | Data Type | Description |
| - | - | - |
| `categories` | Array | An array of categories passed when creating the client. |
| `client_id` | String | The unique identifier for the client. Defined by the API. |
| `client_id_issued_at` | Integer | The date and time the `client_id` was issued, given in Unix time. |
| `client_name` | String | The human-readable name of the client. |
| `client_secret` | String | The client secret issued by the API. |
| `client_secret_expires_at` | Integer | The date and time at which the client secret expires, given in Unix time. `0` indicates the client secret doesn't expire. Defaults to `0`. |
| `grant_types` | Array | The grant types issued to the client. |
| `logo_uri` | String | A URI pointing to a logo for the client application. |
| `redirect_uris` | Array | An array of redirect URIs. |
| `software_id` | String | The unique identifier for the client application. Defined by the data recipient when creating the client. |

## Create a Client

Use this endpoint to create a new client. This endpoint expects a JSON object in the request body with the following attributes defined:

**Parameters**

| Name | Required? | Notes |
| - | - | - |
| `categories` | No | --- |
| `client_name` | Yes | --- |
| `grant_type` | Yes | Only `authorization_code` type supported; `refresh_token` is implied. |
| `logo_uri` | No | --- |
| `redirect_uris` | Yes | This array must contain only one URI. |
| `scope` | Yes | A space-separated list of customer data access rights desired for the client. This list **must** contain `openid` and may contain any subset of the available scopes: `customers` `accounts` `transactions` `statements` `offline_access` is implied and doesn't need to be provided. |
| `software_id` | Yes | --- |

Endpoint: `POST /oauth2/v4/register`

```shell Request theme={null}
curl -i -X POST 'https://base.url.com/oauth2/v4/register' \
-H 'Authorization: Bearer 3cfb93d5-5d87-46e7-b9a6-358c63b8c4cb' \
-H 'Content-Type: application/json' \
-d '{
      "categories": "budgeting,investments,healthcare",
      "client_name": "Centz",
      "grant_type": "authorization_code",
      "logo_uri": "https://centz.example.org/logo.svg",
      "redirect_uris": [
            "https://centz.example.org/redirect"
      ],
      "scope": "openid customers accounts transactions",
      "software_id": "CENTZ-2408aef1-7a67-470c-94a6-a2bba80ebee9"
    }'
```

```json Response theme={null}
{
    "categories": [
        "budgeting",
        "investments",
        "healthcare"
    ],
    "client_id": "yeh8XywAkX101r_Tb_DCtJ_ukxc5lx88qOVPtKdqtmI",
    "client_id_issued_at": 1650055408,
    "client_name": "Centz",
    "client_secret": "UQc-XiTdZMm1x6PYI0FMv_AfJZIVOpeBzdrwiWyQOv8",
    "client_secret_expires_at": 0,
    "grant_types": [
        "authorization_code",
        "refresh_token"
    ],
    "logo_uri": "https://centz.example.org/logo.svg",
    "redirect_uris": [
        "https://centz.example.org/redirect"
    ],
    "software_id": "CENTZ-2408aef1-7a67-470c-94a6-a2bba80ebee9"
}
```

**Invalid Scope Error**

```shell theme={null}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error":"invalid_client_metadata",
  "error_description":"Scope account is not a permitted scope"
}
```

**Invalid DCR Token Error**

```shell theme={null}
HTTP/1.1 401 Unauthorized
```

**Invalid Redirect URI Error**

```shell theme={null}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error":"invalid_redirect_uri",
  "error_description":"Validation failed: Redirect uri must use https"
}
```

## Read a Client

Use this endpoint to read the details of the specified client.

Endpoint `GET /oauth2/v4/register/{client_id}`

```shell Request theme={null}
curl -i -X GET 'https://base.url.com/oauth2/v4/register/yeh8XywAkX101r_Tb_DCtJ_ukxc5lx88qOVPtKdqtmI' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer 3cfb93d5-5d87-46e7-b9a6-358c63b8c4cb'
```

```json Response theme={null}
{
    "categories": [
        "budgeting",
        "investments",
        "healthcare"
    ],
    "client_id": "yeh8XywAkX101r_Tb_DCtJ_ukxc5lx88qOVPtKdqtmI",
    "client_id_issued_at": 1650055408,
    "client_name": "Centz",
    "client_secret": "UQc-XiTdZMm1x6PYI0FMv_AfJZIVOpeBzdrwiWyQOv8",
    "client_secret_expires_at": 0,
    "grant_types": [
        "authorization_code",
        "refresh_token"
    ],
    "logo_uri": "https://centz.example.org/logo.svg",
    "redirect_uris": [
        "https://centz.example.org/redirect"
    ],
    "software_id": "CENTZ-2408aef1-7a67-470c-94a6-a2bba80ebee9"
}
```

## Update a Client

Use this endpoint to update the attributes of the specified client.

> [!NOTE]
>
> **INFO**
>
> No specific parameter is required, but the request body cannot be empty.

**Parameters**

| Name | Required? | Notes |
| - | - | - |
| `categories` | No | ------ |
| `client_name` | No | ------ |
| `logo_uri` | No | ------ |
| `redirect_uris` | No | ------ |
| `software_id` | No | ------ |

Endpoint: `PUT /oauth2/v4/register/{client_id}`

```shell Request theme={null}
curl -i -X PUT 'https://base.url.com/oauth2/v4/register/yeh8XywAkX101r_Tb_DCtJ_ukxc5lx88qOVPtKdqtmI' \
  -H 'Authorization: Bearer 3cfb93d5-5d87-46e7-b9a6-358c63b8c4cb' \
  -H 'Content-Type: application/json' \
  -d '{
        "client_name": "Centz",
        "software_id": "CENTZ-2408aef1-7a67-470c-94a6-a2bba80ebee9",
        "redirect_uris": ["https://centz.example.org/redirect"],
        "categories": "budgeting,investments,healthcare",
        "logo_uri": "https://centz.example.org/logo.svg"
      }'
```

```json Response theme={null}
{
    "categories": [
        "budgeting",
        "investments",
        "healthcare"
    ],
    "client_id": "yeh8XywAkX101r_Tb_DCtJ_ukxc5lx88qOVPtKdqtmI",
    "client_id_issued_at": 1650055408,
    "client_name": "Centz",
    "client_secret": "UQc-XiTdZMm1x6PYI0FMv_AfJZIVOpeBzdrwiWyQOv8",
    "client_secret_expires_at": 0,
    "grant_types": [
        "authorization_code",
        "refresh_token"
    ],
    "logo_uri": "https://centz.example.org/logo.svg",
    "redirect_uris": [
        "https://centz.example.org/redirect"
    ],
    "software_id": "CENTZ-2408aef1-7a67-470c-94a6-a2bba80ebee9"
}
```

## Delete a Client

Use this endpoint to delete the specified client.

> [!WARNING]
>
> Deleting a client will revoke all existing customer consents attached to the application.
>
> This action cannot be undone.

Endpoint: `DELETE /oauth2/v4/register/{client_id}`

```shell Request theme={null}
curl -i -X DELETE 'https://base.url.com/oauth2/v4/register/yeh8XywAkX101r_Tb_DCtJ_ukxc5lx88qOVPtKdqtmI' \
  -H 'Authorization: Bearer 3cfb93d5-5d87-46e7-b9a6-358c63b8c4cb'
```