---
title: "Create client link"
method: POST
path: "/v2/client-links"
tags: ["Client Links API"]
---

# Create client link

`POST /v2/client-links`

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](https://docs.mollie.com/docs/permissions) 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](https://docs.mollie.com/reference/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.

## Headers

- `idempotency-key` string

## Request body

- ClientLinkRequest
  - `resource` string — Indicates the response contains a client link object. Will always contain the string `client-link` for this endpoint.
  - `id` string — The identifier uniquely referring to this client link. Example: `cl_vZCnNQsV2UtfXxYifWKWH`.
  - `owner` object, required — Personal data of your customer.
    - `email` string, required — The email address of your customer. If the domain contains non-ASCII characters, encode it as Punycode per [RFC 3492](https://www.rfc-editor.org/rfc/rfc3492).
    - `givenName` string, required — The given name (first name) of your customer.
    - `familyName` string, required — The family name (surname) of your customer.
    - `locale` 'ca_ES' | 'cs_CZ' | 'da_DK' | 'de_AT' | 'de_CH' | 'de_DE' | 'de_LU' | 'en_BE' | 'en_GB' | 'en_NL' | 'en_US' | 'es_ES' | 'fi_FI' | 'fr_BE' | 'fr_FR' | 'fr_LU' | 'hu_HU' | 'is_IS' | 'it_IT' | 'lt_LT' | 'lv_LV' | 'nb_NO' | 'nl_BE' | 'nl_NL' | 'pl_PL' | 'pt_PT' | 'sk_SK' | 'sv_SE' | 'null', nullable — Sets the language for customer-facing content and communications.
  - `name` string, required — Name of the organization.
  - `address` object, required — Address of the organization.
    - `streetAndNumber` string, nullable — The street name and house number of the organization.
    - `postalCode` string, nullable — The postal code of the organization. Required if a street address is provided and if the country has a postal code system.
    - `city` string, nullable — The city of the organization. Required if a street address is provided.
    - `country` string, required — The country of the address in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
  - `registrationNumber` string, nullable — The registration number of the organization at their local chamber of commerce.
  - `vatNumber` string, nullable — The VAT number of the organization, if based in the European Union. VAT numbers are verified against the international registry *VIES*.
  - `legalEntity` string — The legal entity type of the organization, based on its country of origin. Please refer to the [legal entity list](common-data-types#legal-entity) for all possible options.
  - `registrationOffice` string — The registration office that the organization was registered at. Please refer to the [registration office list](common-data-types#registration-office) for all possible options.
  - `incorporationDate` string, nullable — The incorporation date of the organization (format `YYYY-MM-DD`)
  - `_links` object — An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.
    - `self` Url — In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.
      - `href` string, required — The actual URL string.
      - `type` string, required — The content type of the page or endpoint the URL points to.
    - `clientLink` Url — In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.
      - `href` string, required — The actual URL string.
      - `type` string, required — The content type of the page or endpoint the URL points to.
    - `documentation` Url — In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.
      - `href` string, required — The actual URL string.
      - `type` string, required — The content type of the page or endpoint the URL points to.

## Response `201`

The newly created client link object.

## Other responses

- `404` — No entity with this ID exists.
- `422` — The request contains issues. For example, if the `owner` field is missing.
- `429` — Rate Limit has been reached.

---

[API](https://skmtc.net/mollie/apis/mollie-api.md) · [All operations](https://skmtc.net/mollie/apis/mollie-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mollie/mollie-api/revisions/8b6839e22c14/schema)