Documentation › Dynamic client registration

Dynamic Client Registration

Dynamic client registration is available for developers who create decentralized products, like Ghost or Wordpress, where a single API key can’t be shared between all installations.

A parent API application owned by the developer is used to create children applications on behalf of its users.

It is different from user authentication, where API responses are customized to the logged in user. Instead, one user per installation authenticates to create an API key associated with the installation, allowing each installation to have its own API key.

Since this is not a typical use case, please reach out to the Unsplash Team to let us know about your use case and we will enable the ability for your application.

Once enabled, your application will become a parent application, with the ability to create children applications. The parent application’s Client ID and Secret Key will become special keys that can only be used to start the authorization flow — they cannot be used to query endpoints other than the minimum endpoints needed for this flow. Unlike other API keys, these keys can be public, saved in source code, etc. with no security concerns.

Using the parent application client ID, follow the steps below to create a child API application.

💫 Tip

Without contacting our team, your application will not be able to test this flow. We must enable special privelages for your application.

Step 1

Direct the user to with the following query parameters:

param Description
client_id The parent application Client ID
redirect_uri A URI that handles accepting the Unsplash authorization code and generating the user’s Bearer token (step 3).
response_type Set this to code
scope Set this to public

If necessary the user will be asked to log in/join.

// Example

Step 2

If the user accepts the request and authorizes the creation of the API application, the user will be redirected to the redirect_uri, with the authorization code in the code query parameter.

Step 3

Make a request to POST with the following parameters:

param Description
client_id The parent application Client ID (given to you by Unsplash)
client_secret The parent application secret key (given to you by Unsplash)
redirect_uri A URI that handles creating a new installation-specific client_id (step 4)
code The authorization code supplied to the callback by Unsplash in step 2.
grant_type Value “authorization_code”.

If successful, the response body will be a JSON representation of your user’s access token:

  "access_token": "091343ce13c8ae780065ecb3b13dc903475dd22cb78a05503c2e0c69c5e98044",
  "token_type": "bearer",
  "scope": "public",
  "created_at": 1588259748

Access tokens do not expire.

Step 4

Use this access_token value to register a new Unsplash API application by using it as a one-time Bearer token in a request to POST Pass in the name and description if they exist that best describes the installation. Ideally, set the name equal to the name of the blog/publisher, and in the description include any relevant identifying information, like the domain of the installation and the publisher/blog description if available.

POST /clients
Authorization: Bearer ACCESS_TOKEN


param Description
name The name of the application.
description Optional.


201 Created
  "name": "Beverly's Plugin instance",
  "description": "",
  "client_id": "a374a6d26de75ce50e3e2013"

Step 5

This newly created API application and its returned client ID is the one that should remain private to each installation and an be used for accessing the API on behalf of the installation. It will have a rate limit of 3000 requests per hour and be associated to the user’s Unsplash account.

Currently, all applications created in this way are whitelisted to a default set of endpoints:

If your application will need access to more endpoints, let our team know when registering for a parent application.