Authentication

All endpoints in the Shutterstock API require authentication. The API accepts HTTP basic authentication for some endpoints and OAuth authentication for all endpoints.

All requests must also specify a User-Agent header. The value of this header should either be the type of client, such as "NodeJS" or "PHP," or the name of the customer's application.

In the API reference, each endpoint is labeled with the types of authentication it accepts and the OAuth scopes it requires, if any. In general, HTTP basic authentication is sufficient for search queries and for getting information about pieces of media. The API requires OAuth authentication for actions that require customers to log in to shutterstock.com, such as licensing and downloading media.

Before you authenticate to the API, you need an API subscription and an API application. See Subscriptions.

Subscriptions

To access the API, you need an API application and either a free or paid API subscription. The type of subscription determines which media library you have access to and what level of access you have to other features such as reverse image search. To set up a paid API subscription, see the API subscription page. To set up a free API subscription, create an application and select the free subscription as described in Applications.

These API subscriptions are separate from the subscriptions that are available on the Shutterstock web site, so be sure to get an API subscription if you want to work with the API. See https://www.shutterstock.com/api/pricing.

You can use an API subscription to license and download media only with the API; API subscriptions don't work on the Shutterstock web site. If you have a subscription that does not include API access and want to use it with the API, contact us.

For a summary of what each type of API subscription provides, see Subscriptions in the API reference.

Applications

To access the REST API you need an application, which represents the application, program, or computer commands that are accessing the API. To use the API, you need the application's consumer key and consumer secret, which are shown on the https://www.shutterstock.com/account/developers/apps page.

When you have the application's consumer key and consumer secret, you can use them to access the API directly or to request a token that you can use to access the API. For more information on these methods of authentication, see Authentication.

To create an application:

The new application appears on the My apps page. Each application has a consumer key and a consumer secret. You use this consumer key and consumer secret either to use the API directly with basic authentication or to request a token for OAuth authentication; see Authentication. Do not share your key and secret, because they can be used to access your account through the API.

Products

Each application has access to one or more API products. These products control the media library that the application accesses and whether the application can access other features such as reverse image search. These products are separate from the subscriptions that control how many assets you can license and download and what level of access the application has to other features.

To tell which API products your application is using, open your applications, expand your application, and go to its Details tab.

Basic authentication

The API accepts HTTP basic authentication (also known as basic authentication) for some endpoints that do not access specific customer information. Follow these steps to use basic authentication:

cURLCLIPHPJavaScript


curl -X GET --user 123abc456def:1a2b3c4d \
https://api.shutterstock.com/v2/images/search \
--data-urlencode "query=sunrise"

API endpoints that require an OAuth scope do not accept basic authentication. To use these endpoints, you must use OAuth authentication.

OAuth authentication

Most endpoints require OAuth 2.0 authentication. In this type of authentication, you use an application and an individual user's login credentials to obtain a token. Then you can use that token as credentials for API requests in place of a user name and password.

Some endpoints require one or more scopes, or permissions, which let the user control what the application can do with the token. For example, to edit a user's collections, the token must include the collections.edit scope. Applications can request multiple tokens with different scopes or a single token with multiple scopes.

Getting tokens from your account page

As a shortcut, you can get a token directly from an application on your account page:

The popup window shows the token. Copy it immediately, because it is shown only once. The token is valid until the user account that you logged in with changes its password or email address.

Keep this token private, because other people could use it to access the account's subscriptions and media.

Now you can use the token to authenticate to the API. See Authenticating with OAuth tokens.

Getting tokens from application code

To get an OAuth token in your application code, follow these steps:

Use the POST /v2/oauth/access_token endpoint, as in the following example. The parameters for this endpoint include the application's consumer key, consumer secret, and the code you got from the URL in the previous step:

cURLCLIPHPJavaScript


curl -X POST "https://api.shutterstock.com/v2/oauth/access_token" \
--data-urlencode "client_id=860bde70bb335163e2e4" \
--data-urlencode "client_secret=225d245d28e5b1a37db7fd4ceb8cdf360a3ae5a7" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "expires=false" \
--data-urlencode "code=VaRLQ3rICmWjGr4ciI-GwR"

This endpoint returns the access token in a JSON response. If you requested a token that does not expire, the API returns an access token that starts with v2/, as in this example:

{
  "access_token": "v2/ODYwYmRlNzBiYjMzNTE2M2UyZTQvMTc4NzI2OTM4L2N1c3RvbWVyLzIvWEtXR01HQ1FaVHRLOG85a",
  "token_type": "Bearer"
}

If you requested a token that expires, the API returns an access token that starts with 1/ and a refresh token, as in this example. You will need the refresh token to refresh the access token later.

{
  "access_token": "1/eyJjbGllbnRfaWQiOiJjNDc4Yi0yNjYzMC1",
  "expires_in": 3600,
  "token_type": "Bearer",
  "user_token": "eyJhbGciOiTtcXy71dhyfjBVU",
  "refresh_token": "3/d_0F6_AmGRO5a7NNhjdCwobDudbdvDNdPQTWV1IovpWPgWy"
}

Keep this token private, because other people could use it to access the account's subscriptions and media.

Authenticating with OAuth tokens

Now that you have a token, you can use it to access the API by passing it as an authorization header, as in this example of searching for images:

cURLCLIPHPJavaScript


curl -X GET "https://api.shutterstock.com/v2/images/search" \
--header "Authorization: Bearer v2/ODYwYmRlNzBiYjMzNTE2M2UyZTQvMTc4NzI2OTM4L2N1c3RvbWVyLzIvWEtXR01HQ1FaVHRLOG85a" \
-G \
--data-urlencode "query=kites" \
--data-urlencode "image_type=photo" \
--data-urlencode "page=1" \
--data-urlencode "per_page=5" \
--data-urlencode "sort=popular" \
--data-urlencode "view=minimal"

Further examples in this documentation assume that you put the token in the SHUTTERSTOCK_API_TOKEN environment variable, but you can also store the token in a variable in your code.

You can use the same application to get tokens for any number of users. Just repeat the request to GET /v2/oauth/authorize with the application information and then sign in as a different user. Each token is tied to the user's account.

Refreshing tokens

If you requested a token with the parameter expires=true, the token begins with "1/", and it expires in one hour. You can refresh the token to continue using it.

If you requested a token that does not expire, the token does not need to be refreshed. This type of token is valid until the user account that is associated with the token changes its password or email address.

To refresh a token that expires, pass the refresh token, which begins with "3/", to the POST /v2/oauth/access_token endpoint. You must also pass either the consumer secret from the application or the user ID of the user account that is associated with the token. Use these parameters:

The response includes the existing refresh token and a new token that is valid for one hour.

cURLCLIPHPJavaScript


curl -X POST "https://api.shutterstock.com/v2/oauth/access_token" \
--data-urlencode "client_id=860bde70bb335163e2e4" \
--data-urlencode "client_secret=225d245d28e5b1a37db7fd4ceb8cdf360a3ae5a7"
--data-urlencode "grant_type=refresh_token" \
--data-urlencode "refresh_token=3/d_0F6_AmGRO5a7NNhjdCwobDudbdvDNdPQTWV1IovpW"

Common errors

Redirect URI mismatch

For security reasons, the callback URI that you send to GET /v2/oauth/authorize must use a host name that is registered with your application. If you provide a redirect_uri that does not use one of your application's host names, Shutterstock displays an error message to your users. The error indicates that your application was blocked from doing something potentially dangerous:

Invalid redirect URI:
The Redirect URI http://someplace.com doesn't match the valid hostnames for this client.
invalid_redirect_url

Access denied

If the user rejects access to your application, Shutterstock returns parameters that summarize the error:

http://localhost:3000/callback?error=access_denied
  &error_description=The user denied the authorization request.
  &error_reason=user_denied

You can't get an access token if the user chooses not to authorize your application. In this case, your application should fail gracefully. Often, users close the window or press the browser back button rather than explicitly decline permission, so your application may not get this error.

Missing required parameters

If you leave out a required parameter, you receive an error response status code of 400 with the message "Validation failed," as in this example:

{
  "message": "Validation failed",
  "errors": [{
    "code": "VALIDATION_OBJECT_REQUIRED",
    "message": "Missing required property: client_id"
  }]
}

If you leave out the client_id or client_secret parameters, or if they don't match, you receive an error response status code of 403 with text "Invalid client_id/secret given."

OAuth scopes

Most endpoints require an access token with one or more scopes, or permissions. You can see the scopes that an individual endpoint requires in the API reference.

The following table shows the available scopes.