Sign in
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.

Changes

Changed in 6 of the 79 revisions of this API.1711

  • 86a9cd830b0622See the full diff
    • ●

      added the new en_BE enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ●

      added the new en_NL enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ○

      added the new en_BE enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new en_NL enum value to the request property /////

      request-property-enum-value-added

  • 64c0511a62bc112See the full diff
    • ▲

      removed the enum value null of the request property /////

      request-property-enum-value-removed

    • ●

      added the new undefined enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ○

      added the new undefined enum value to the request property /////

      request-property-enum-value-added

    • ○

      removed the null enum value from the ///// response property for the response status

      response-property-enum-value-removed

  • 4d4ab81fb2d522See the full diff
    • ●

      added the new cs_CZ enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ●

      added the new sk_SK enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ○

      added the new cs_CZ enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new sk_SK enum value to the request property /////

      request-property-enum-value-added

  • 7cab62b218301See the full diff
    • ○

      added the non-success response with the status

      response-non-success-status-added

  • ef4b5a97b56a2See the full diff
    • ○

      the endpoint scheme security advancedAccessToken was added to the API

      api-security-added

    • ○

      the endpoint scheme security organizationAccessToken was removed from the API

      api-security-removed

    This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • f3d6346a141222See the full diff
    • ●

      added the new de_LU enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ●

      added the new fr_LU enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ○

      added the new de_LU enum value to the request property /////

      request-property-enum-value-added

    • ○

      added the new fr_LU enum value to the request property /////

      request-property-enum-value-added

Of the 79 revisions, 9 have no diff computed.