Authorization

Many Getty Images API operations require authorization. The Getty Images API implements the OAuth 2.0 Authorization Framework to provide authorization to third-party applications and grant access tokens to them.

Once an access token is obtained, it should be reused until it expires. Calling to get a new token more often than needed should be avoided, as those calls are counted against a customer’s rate limit.

Tokens obtained via the resource owner and authorization code grants can be refreshed with a refresh token without the need to re-prompt users for their credentials. Both access and refresh tokens should be considered secrets and should be treated accordingly with regards to storage for later use.

What is OAuth?

OAuth (Open Authorization) is an open security protocol designed to protect system and user credentials in client applications. OAuth allows users to authorize a client application to access user functionality without requiring the client application to directly handle the user’s credentials. OAuth improves security by reducing the exposure of end user credentials. Getty Images supports OAuth 2.0

Important Terminology

OAuth defines a number of roles and terms. Some of the following are taken directly from OAuth 2.0 RFC 6749.

TermDefinitionExample (if applicable)
Resource OwnerAn entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.A Getty Images or iStock end-user.
Protected ResourceResource, stored on or provided by a server, that requires authorization to access it.Images, videos, boards, etc.
Resource ServerThe server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.api.gettyimages.com
Authorization ServerThe server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.Getty Images’ OAuth server
ClientAn application making protected resource requests on behalf of the resource owner and with its authorization. The term “client” does not imply any particular implementation characteristics (e.g., whether the application executes on a server, a desktop, or other devices)Getty Images API client
Client CredentialsCredentials which identify a client.API key and secret for the client.
Access TokenToken provided by the authorization server to the client to authorize access to resources.
Token RevocationMeans of revoking an access token. Getty Images or a user can revoke an access token if suspicious activity is detected.
Client TypeA client type is assigned to a client application based on their ability to authenticate securely with the authorization server.Public or confidential (see the OAuth 2.0 RFC for more info)
PKCEProof Key for Code Exchange (see the OAuth 2.0 PKCE RFC) for more info.
Code VerifierPKCE Requirement A cryptographically random string that is used to correlate the authorization request to the token request.
Code ChallengePKCE Requirement A challenge derived from the code verifier that is sent in the authorization request, to be verified against later.
Code Challenge MethodPKCE Requirement The method that was used to derive code challenge. plain or S256

Authorization Grant Types

Authorization GrantClient EnvironmentEntities Required
Authorization CodeWeb application with a server-side component which can secure the API secretAPI key and secret, User ID and password, code verifier, code challenge and code challenge method
Client CredentialsClient application is also the resource owner.API key and secret
Implicit GrantClient-side application, where the application cannot secure the API secretAPI key, User ID and password
Resource Owner Password CredentialsResource owner has high degree of trust with the client application.API key and secret, User ID and password

Authorization Code Grant

Summary

Getty Images requires use of the authorization code grant for third-party web applications that have client and server components, or mobile applications.

  1. Client application makes a GET request to the authorization endpoint at https://api.gettyimages.com/oauth2/auth passing the following information:

    • client_id: API key.
    • response_type: code.
    • redirect_uri: URI that has been registered with the Getty Images API to receive the authorization code. Parameters may be added that are not registered.
    • state: Optional state data which will be passed back to the client in the final redirect.
    • code_challenge: Hashed and Base64url encoded version of code verifier:
      • It is important to note that this value is not just encoded as Base64, but as Base64url.
      • The formal definition of Base64url (or “Base 64 Encoding with URL and Filename Safe Alphabet”) can be found in RFC 4648
      • A simple C# implementation can be found in the Appendix A of RFC 7636 for PKCE
    • code_challenge_method: The hash mechanism used (plain or S256)
  2. Client application is redirected to the Getty Images sign-in page.

  3. End user signs in with their Getty Images or iStock credentials and clicks Authorize.

  4. Client is redirected back to the redirect URI with the authorization code in the query string.

  5. Application makes a POST request to the token endpoint (https://api.gettyimages.com/oauth2/token):

    • content-type: This is an HTTP header. Value is: application/x-www-form-urlencoded
    • grant_type: authorization_code
    • code: The authorization code received from, the Getty Images authorization server.
    • redirect_uri: The redirect URI that was used to make the initial request.
    • client_id: API key.
    • client_secret: Required only if the client type is confidential. If the client type is public, sending this parameter will cause the request to fail. Mobile applications should not use client secret as it could be exposed to an attacker.
    • code_verifier: The cryptographic string used to generate Code Challenge in original authorization code request.
  6. Getty Images authorization server responds with the token response:

    • access_token: The access token to be used to authorize other API calls.
    • token_type: Bearer.
    • expires_in: Number of seconds until the access token expires.
    • refresh_token: A token which can be used to refresh the access token. Used with the refresh token grant instead of prompting the end-user for their credentials repeatedly.

Find more information about the authorization code grant at the OAuth 2.0 RFC

Example Authorization Code Request

GET https://api.gettyimages.com/oauth2/auth?client_id=abc123&response_type=code&state=datasentfromclient&redirect_uri=https%3A%2F%2Fyourhost%2Fauthreceiver&code_challenge=encodedcodeverifier&code_challenge_method=S256 HTTP/1.1
Host: api.gettyimages.com

Example Authorization Code Response

HTTP/1.1 302 Found
Location: https://yourhost/authreceiver?code=def456&state=datasentfromclient

Example Access Token Request

POST https://api.gettyimages.com/oauth2/token HTTP/1.1
Host: api.gettyimages.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=abc123&client_secret=yoursecret&redirect_uri=https%3A%2F%2Fyourhost%2Fauthreceiver&code=def456&code_verifier=cryptostring

Example Access Token Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "accesstokendata",
    "token_type": "Bearer",
    "expires_in": 1800,
    "refresh_token": "refreshtokendata"
}

Token Expiration and Revocation

Tokens issued by the authorization code grant are valid for at most 30 minutes. Be sure to check the expires_in property of the response to determine when the access token actually expires. If the client application needs to access content for the user longer that 30 minutes, it can use the refresh token to get a new access token that will also be valid for 30 minutes. The refresh token is valid for one year and can be used as many times as needed within that one year to get a new access token. The refresh token cannot be used for API access.

Client Credentials Grant

Summary

https://datatracker.ietf.org/doc/html/rfc6749#section-4.4
Client Credentials flow is for client applications that will not have individual users. An application token is created and limits the client application to operations that do not need user credentials.

  1. Client application calls the token endpoint with the following information in the request:

    • grant_type: client_credentials.
    • client_id: API key.
    • client_secret: API secret.
  2. Client receives the following response:

    • access_token: The access token to be used to authorize other API calls.
    • token_type: Bearer.
    • expires_in: Number of seconds until the access token expires.
Example request:
POST https://api.gettyimages.com/oauth2/token HTTP/1.1
Host: api.gettyimages.com
Content-Type: application/x-www-form-urlencoded

client_id=abc123&client_secret=yoursecret&grant_type=client_credentials
Example response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
        "access_token":"accesstokendata",
        "token_type":"Bearer",
        "expires_in":1800,
}

Our code samples repository contains a sample client credentials call using curl.

Token Expiration and Revocation

Tokens issued by the client credentials grant are good for at most 30 minutes. Be sure to check the expires_in property of the response to determine when the access token actually expires. Once the access token has expired, a request for a new access token is required.

Find more information about client credentials grant at the OAuth 2.0 RFC

Implicit Grant

Summary

Getty Images requires the use of the implicit grant for third-party web-based client applications without a server-side component. In this flow, the user authorizes the application to access their protected resources using the Getty Images authorization server. Developers follow these steps to get an access token for their application:

  1. Client application makes a *GET request to the authorization endpoint at https://api.gettyimages.com/oauth2/auth and passes in the following information:

    • client_id: API key.
    • response_type: token.
    • redirect_uri: URI that has been registered with the Getty Images API to receive the access token. Parameters may be added that are not registered.
    • state: Optional state data which will be passed back to the client in the final redirect
  2. Client application is redirected to the Getty Images sign-in page.

  3. End user signs in with their Getty Images or iStock credentials, and clicks Authorize.

  4. If authorization is successful, client is redirected back to the redirect URI with the token in the URI fragment.

Find more information about the implicit grant at the OAuth 2.0 RFC

Example request:

GET https://api.gettyimages.com/oauth2/auth/?response_type=token&client_id=abc123&state=datasentfromclient&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: api.gettyimages.com

Example response:

HTTP/1.1 302 Found
Location: https://client.example.com/cb#access_token=accesstokendata&state=xyz&token_type=bearer

Token Expiration and Revocation

Tokens issued by the implicit grant are long-lived, i.e., their expiration time is longer than 30 minutes (usually one year). Some resources require a token that has been issued within a certain time period. For instance, search functionality accepts any unexpired token whereas download functionality requires a token to be issued within the last 30 days.

Once an access token is no longer valid (has expired) for a given resource, a new access token must be retrieved to access that resource. The implicit grant does not support access token refresh. A new access token must be requested once it expires.

Access tokens will be revoked when the user changes their password. Revoked tokens cannot be used for any API access.

Resource Owner Grant

Summary

The resource owner grant is available to Getty Images partner applications capable of protecting the client secret and the user’s credentials. Used when the client application and user accounts are owned by the same organization.

  1. Client application makes a POST request to the token endpoint passing the following information:

    • grant_type: password.
    • username: The user’s login ID.
    • password: The user’s password.
    • client_id: API key.
    • client_secret: API secret.
  2. Client receives the following response:

    • access_token: The access token to be used to authorize other API calls.
    • token_type: Bearer.
    • expires_in: Number of seconds until the access token expires.
    • refresh_token: A token which can be used to refresh the access token. Used with the refresh token grant instead of prompting the end-user for their credentials repeatedly.
Example Resource Owner Request
POST https://api.gettyimages.com/oauth2/token HTTP/1.1
Host: api.gettyimages.com
Content-Type: application/x-www-form-urlencoded

client_id=abc123&client_secret=yoursecret&grant_type=password&username=usersloginid&password=userspassword
Example Resource Owner Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
        "access_token":"accesstokendata",
        "token_type":"Bearer",
        "expires_in":1800,
        "refresh_token":"refreshtokendata"
}

Our code samples repository contains a sample resource owner call using curl.

Example Refresh Token Request
POST https://api.gettyimages.com/oauth2/token HTTP/1.1
Host: api.gettyimages.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=abc123&client_secret=yoursecret&refresh_token=refreshtokendata

Token Expiration and Revocation

Tokens issued by the resource owner grant are valid for at most 30 minutes. Be sure to check the expires_in property of the response to determine when the access token actually expires. If the client application needs to access content for the user longer that 30 minutes, it can use the refresh token to get a new access token that will also be valid for 30 minutes. The refresh token is valid for one year and can be used as many times as needed within that one year to get a new access token. The refresh token cannot be used for API access.

Refresh tokens can be revoked when the user changes their password. Revoked tokens cannot be used for any API access.

Find more information about the resource owner grant at the OAuth 2.0 RFC

Redirect URIs for Authorization grants

Authentication workflows requiring a Redirect URI (Implicit or Authorization Code grant) need to be registered with the Getty Images API before access token requests can be made. Redirect URIs must use HTTPS.

Redirect URIs that do not need to leave the device, e.g. localhost and 127.0.0.1, do not require registration or HTTPS. The path portion of the URI may be anything that makes sense for the application in question.

References

OAuth 2.0 Specification