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 https://unsplash.dogedoge.com/oauth/authorize 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
GET https://unsplash.com/oauth/authorize?client_id=PARENT_APPLICATION_CLIENT_ID&redirect_uri=https://mywordpressinstall.com/unsplash_callback&response_type=code&scope=public

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 https://unsplash.dogedoge.com/oauth/token 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 api.unsplash.com/clients. 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

Parameters

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

Response

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.