v55

latestOpenAPI 3.1.0CC-BY-NC-SA-4.0raw.githubusercontent.com2026-08-011243791.8 MB

Client Links API

Create client link

Link a new or existing organization to your OAuth application, in effect creating a new client. The response contains a clientLink where you should redirect your customer to.

Redirecting the Customer

The clientLink URL behaves similarly to a standard OAuth authorization URL. Therefore, after receiving the clientLink URL in the API response, you need to append the following query parameters before redirecting the customer:

client_id string (required)

The client ID you received when you registered your OAuth app. The ID starts with app_. For example: app_abc123qwerty.
state string (required)

A random string generated by your app to prevent CSRF attacks. This will be reflected in the state query parameter when the user returns to the redirect_uri after authorizing your app.
scope string (required)

A space-separated list of permissions ('scopes') your app requires. See the permissions list for more information about the available scopes.

We recommend at least : onboarding.read onboarding.write
approval_prompt string

Can be set to force to force showing the consent screen to the merchant, even when it is not necessary. If you force an approval prompt and the user creates a new authorization, previously active authorizations will be revoked.

Possible values: auto force (default: auto)

Example of a Complete Redirect URL

After adding the above url parameter your URL will look something like this and you can redirect your client to this page:

https://my.mollie.com/dashboard/client-link/{id}?client_id={your_client_id}&state={unique_state}&scope=onboarding.read%20onboarding.write

Error Handling

Error handling is also dealt with similar to the Authorize endpoint: the customer is redirected back to your app's redirect URL with the error and error_description parameters added to the URL.

🚧

A client link must be used within 30 days of creation. After that period, it will expire and you will need to create a new client link.

post/v2/client-links

Headers

idempotency-keystring

Example:123e4567-e89b-12d3-a456-426

A unique key to ensure idempotent requests. This key should be a UUID v4 string.

Request body

resourcestring

Indicates the response contains a client link object. Will always contain the string client-link for this endpoint.

idstring

The identifier uniquely referring to this client link. Example: cl_vZCnNQsV2UtfXxYifWKWH.

namestring required

Name of the organization.

registrationNumberstring nullable

The registration number of the organization at their local chamber of commerce.

vatNumberstring nullable

The VAT number of the organization, if based in the European Union. VAT numbers are verified against the international registry VIES.

legalEntitystring

The legal entity type of the organization, based on its country of origin. Please refer to the legal entity list for all possible options.

registrationOfficestring

The registration office that the organization was registered at. Please refer to the registration office list for all possible options.

incorporationDatestring nullable

The incorporation date of the organization (format YYYY-MM-DD)

Example request

{
  "resource": "client-link",
  "id": "cl_vZCnNQsV2UtfXxYifWKWH",
  "owner": {
    "email": "john@example.org",
    "givenName": "John",
    "familyName": "Doe",
    "locale": "en_US"
  },
  "name": "Acme Corporation",
  "address": {
    "streetAndNumber": "Main Street 123",
    "postalCode": "1234AB",
    "city": "Amsterdam",
    "country": "NL"
  },
  "vatNumber": "NL123456789B01",
  "legalEntity": "nl-bv",
  "registrationOffice": "aachen",
  "incorporationDate": "2024-12-24",
  "_links": {
    "self": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "clientLink": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "documentation": {
      "href": "https://...",
      "type": "application/hal+json"
    }
  }
}

Response

The newly created client link object.