Dynamic Client Registration - MX Documentation

This API supports the automated onboarding for data recipient applications, called Dynamic Client Registration (DCR). It follows OAuth specification RFC7951 with some limitatations 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`	Creates and returns a new client.
`GET /oauth2/v4/register/${client_id}`	Returns information about the specified client.
`PUT /oauth2/v4/register/${client_id}`	Updates and returns information about the specified client.
`DELETE /oauth2/v4/register/${client_id}`	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

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"
    }'

{
    "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

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

HTTP/1.1 401 Unauthorized

Invalid Redirect URI Error

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}

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'

{
    "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.

INFONo 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}

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"
      }'

{
    "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.

WARNINGDeleting a client will revoke all existing customer consents attached to the application.This action cannot be undone.

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

curl -i -X DELETE 'https://base.url.com/oauth2/v4/register/yeh8XywAkX101r_Tb_DCtJ_ukxc5lx88qOVPtKdqtmI' \
  -H 'Authorization: Bearer 3cfb93d5-5d87-46e7-b9a6-358c63b8c4cb'

​Client Response Fields

​Create a Client

​Read a Client

​Update a Client

​Delete a Client

Client Response Fields

Create a Client

Read a Client

Update a Client

Delete a Client