FAQs: Using OAuth 2.0 to access Getty Images APIs

Getty Images APIs require the use of the OAuth 2.0 protocol for the retrieval of authorization and authentication tokens. These tokens are used to:

While it is possible to make some API calls with only an API key (for example, the search endpoints /v3/search/images and /v3/images do not require an authorization token), we do not recommend this because the response will not be wholly accurate. For example, search requests made with only a key will return assets you cannot use because the assets fall outside the scope of the license granted for your use.

Frequently asked authorization questions

How do I ensure that my search results contain only images or videos that I have a license to use?

Always include a token in the header of your Search, Images and Videos request. The token identifies who you are and what assets you have a license to use so that the search engine returns only assets from that collection of content.

When making a download request, I get a “not authorized” error. Why?

One reason you may be getting a “not authorized” error is because the image or video you are trying to download is not within the scope of your license agreement. Another reason is that a token is required for all download requests, and your request may be missing a token in the HTTP authorization header.

Does a token expire?

Yes. Tokens generated by Client Credentials and Resource Owner have a lifespan of 30 minutes.

How do I let users sign in with their Getty Images username?

The OAuth 2.0 Implicit Grant flow has been implemented for this purpose. See the Authorization workflows for more information about Implicit Grant.

Authorization workflows

The Getty Images API uses the OAuth 2.0 protocol to grant client applications access to API functionality. Your client application will use OAuth 2.0 to request an access token from the Getty Images Authorization Server, extract a token from the response, and then send the token back to the Getty Images API that you want access to such as searching and downloading images. The Getty Images API supports the following three OAuth 2.0 flows:

Which OAuth 2.0 Flow should I use?

If

Then

You received an API key by registering for an account on the Getty Images API site

Your key is automatically configured to use the Client Credential flow.

You received an API key by registering for an account on the Getty Images API site AND you are ready to commercialize your application

  • Work with a Getty Images account manager to initiate a licensing agreement between your company and Getty Images.
  • Work with a Getty Images operations manager to determine which OAuth 2.0 flow is appropriate for your application.

OAuth 2.0 flows supported by Getty Images API

Client Credentials

Client Credentials flow is for client applications that will not have individual users. A Sandbox application, which is intended for trial development and does not require a licensing agreement, can only use Client Credential flow.

If your company has a licensing agreement with Getty Images that grants access to specific images, using the Client Credentials flow for search requests will give you results that do not accurately reflect the content you have access to and you will not be able to download files. To get search results and to download assets that are within the scope of your license agreement, your key must be configured as a fully authorized token when using Client Credentials. To find out more about a particular configuration, contact a Getty Images account manager.

The Client Credential flow grants a 30-minute access token. Once the token has expired, you must request another token. Most applications retrieve a new token prior to the current one expiring.

Getting the Client Credentials token
  1. Open the Getty Images web-based API tool.
  2. In the left column, click OAuth2, and then click POST /oauth2/token – Client Credentials.
  3. In the client_id box, enter your Sandbox API key.

    How do I get a Sandbox API key?

  4. In the client_secret box, enter your API secret.

    Where do I find my API secret?

    Open the Getty Images API site, and in the upper-right navigation bar, click Sign In. Enter your username and password, click Sign In, and navigate the the My account page.

  5. Click Get Token

    Notes

    • Use this token in your calls to the API endpoints.
    • The client credential flow grants a 30-minute access token. Once the token has expired, you must request another token.
Resource Owner

Use this flow if your company has a licensing agreement with Getty Images. This flow returns search results that accurately reflect assets that your application has been granted access to, and will allow download of assets against your license agreement.

In this flow, you submit the username and password of your application, along with your API key and secret. The API grants permission for your application to receive search results relevant to the assets that are within the scope of your license agreement.

The Resource Owner flow grants a 30-minute access token. If the client application needs to access content longer than 30 minutes, the application can use the refresh token to obtain a new access token that will also be valid for 30 minutes. The refresh token cannot be used directly for API access. The refresh token is valid for one year and can be used to retrieve another 30-minute access token by calling the token endpoint with a grant type of refresh_token. Note that if the password is changed, the token will no longer be valid.

Getting the Resource Owner Grant token
  1. Open the Getty Images web-based API tool.
  2. In the left column, click OAuth2, and then click POST /oauth2/token – Resource Owner Grant.

  3. In the client_id box, enter your API key.
  4. How do I get a Sandbox API key?

  5. In the client_secret box, enter your API secret.

    Where do I find my API secret?

    Open the Getty Images API site, and in the upper-right navigation bar, click Sign in. Enter your username and password, click Sign in, and then navigate to the My account page.

  6. In the username box, enter your username.
  7. In the password box, enter your user password.
  8. Click Get Token.
Getting the Refresh token
  1. Open the Getty Images web-based API tool.
  2. In the left column, click OAuth2, and then click POST /oauth2/token – Refresh Token.

  3. In the client_id box, enter your API key.
  4. How do I get a Sandbox API key?

  5. In the client_secret box, enter your API secret.

    Where do I find my API secret?

    Open the Getty Images API site, and in the upper-right navigation bar, click Sign in. Enter your username and password, click Sign in, and then navigate to the My account page.

  6. In the refresh_token box, enter the refresh_token value that you received as a response to your initial resource owner token request.
Implicit Grant

In this flow, the client application prompts users to sign in with their Getty Images username and password. Commonly used by applications whose users are also Getty Images customers (CMSs, DAMs, plug-ins, and so on), this flow enables the client application to return relevant search results of assets that fall within the scope of the Getty Images License Agreement granted to users.

Users are directed to the Getty Images sign in page to enter a username and password, and then redirected to the application. The token generated through this flow is valid for one year.

Once an access token has expired for a given resource, a new access token must be retrieved to access that resource. The Implicit Grant flow does not support access token refresh. New access tokens must be retrieved through the Implicit Grant flow. If the password is changed, the token will no longer be valid.

  1. Client application calls the OAuth2 endpoint (for example, https://api.gettyimages.com/oauth2/auth/ and passes the following information:
    • API key / Client ID
    • Redirect URI that has been registered with the Getty Images API (parameters may be added that are not registered)
    • Response type of token
    • State (optional)
  2. Client application redirects to the Getty Images sign-in page, whose location is provided in the response to step 1.
  3. The end user signs in with their Getty Images or Thinkstock username and password, and then clicks Authorize.
  4. The API verifies the client and user credentials, and then redirects to the client application with a long-lived access token.