Documentation › User authentication workflow

User Authentication Workflow

If you’re taking actions on behalf of users or accessing information customized per user, then you’ll need to authenticate and authorize users using the user authentication workflow described below.

The Unsplash API uses OAuth2 to authenticate and authorize Unsplash users. Unsplash’s OAuth2 paths live at

💫 Tip

Most endpoints do not need to be authenticated by an individual user to be accessed and can instead be accessed with public authentication. Endpoints that require user authentication will be explicitly marked with the required scopes.

Authorization workflow

This process is described below in detail. However, many libraries exist to simplify the process. If you are using one of the Unsplash API client libraries, see their documentation for how to handle user authentication.

  1. Direct the user to with the following query parameters:

    param Description
    client_id Your application’s access key.
    redirect_uri A URI you control that handles successful user authorization.
    response_type The access response type you are requesting. The authorization workflow Unsplash supports requires the value “code” here.
    scope A +-separated list of requested scopes. e.g. public+read_user

    If necessary the user will be asked to log in. They will be presented with the list of permission scopes being requested and asked to authorize.

  2. If the user accepts the request, the user will be redirected to the redirect_uri, with the authorization code in the code query parameter.

  3. Make a POST request to with the following parameters:

    param Description
    client_id Your application’s access key.
    client_secret Your application’s secret key.
    redirect_uri Your application’s redirect URI.
    code The authorization code supplied to the callback by Unsplash.
    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 read_photos write_photos",
       "created_at": 1436544465

    Access tokens do not expire.

  4. On future requests, send OAuth Bearer access token via the HTTP Authorization header:

     Authorization: Bearer ACCESS_TOKEN

Permission scopes

To write data on behalf of a user or to access their private data, you must request additional permission scopes from them. The scopes are:

Scope Description
public Default. Read public data.
read_user Access user’s private data.
write_user Update the user’s profile.
read_photos Read private data from the user’s photos.
write_photos Update photos on the user’s behalf.
write_likes Like or unlike a photo on the user’s behalf.
write_followers Follow or unfollow a user on the user’s behalf.
read_collections View a user’s private collections.
write_collections Create and update a user’s collections.

When authorizing your application, the user will be presented with a list of permission scopes being requested.