Getting Started

All endpoints in API v2 require authentication facilitated by an application. There are three ways to authenticate.

Basic Authentication

You can use basic authentication to make requests against API v2 as long as the endpoint does not require an OAuth scope. Please note that this form of authentication does not require an access token to be passed in via headers.

  1. Create an application or use an existing application to obtain your client_id and client_secret.

  2. Using your client_id and client_secret, you can access the endpoints that do not require OAuth scopes. Here is an example of a workflow using basic authentication.

    1. Make an image search request using your client_id and client_secret.

      $ curl "https://${client_id}:${client_secret}@api.shutterstock.com/v2/images/search?query=donkey"
      
    2. You can paginate the search using page and per_page query parameters.

      $ curl "https://${client_id}:${client_secret}@api.shutterstock.com/v2/images/search?query=donkey&page=2&per_page=1"
      
    3. You can further restrict the data returned by all requests using the fields parameter (see Google Partial Responses for supported syntax).

      $ curl "https://${client_id}:${client_secret}@api.shutterstock.com/v2/images/search?query=donkey&page=2&per_page=1&fields=data(id,description)"
      

OAuth 2.0

You can use OAuth 2.0 to make requests against API v2 for endpoints that require scope. This is useful when your integration requires users to log into and access information about their Shutterstock account. Please note that this form of authentication requires an access token be passed in via headers.

  1. Create an application or use an existing application.

  2. Fetch an access token. There are 2 ways to obtain this token.

Manual

You can manually retrieve the access token by entering the desired scopes and then clicking Get Access Token button on the application page (your permission may be required).

Automated

If you want to use a token from within your integration, you will need to periodically refresh it using a refresh token.

  1. Retrieve your application's refresh token via applications.

  2. Once you have a refresh token you can use that to retrieve an access token without having to re-login. Please note that access tokens expire every hour, so you will need to do this on a regular basis. You can check if your token has expired by making a request to an endpoint. If you receive a 401 status code, you should refresh your access token, store it and retry the request.

Single User Integration

If your API integration involves the use of only one user account (as example, to license images under one enterprise account) without needing to implement the OAuth 2.0 flow within your client application, please review the Single User Integration guide.