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

💫 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.

Direct the user to https://unsplash.dogedoge.com/oauth/authorize 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.

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

Make a POST request to https://unsplash.dogedoge.com/oauth/token 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.

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.