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.

Term Definition Example (if applicable)
Resource Owner An 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 Resource Resource, stored on or provided by a server, that requires authorization to access it. Images, videos, boards, etc.
Resource Server The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens. api.gettyimages.com
Authorization Server The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization. Getty Images’ OAuth server
Client An 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 Credentials Credentials which identify a client. API key and secret for the client.
Access Token Token provided by the authorization server to the client to authorize access to resources.
Token Revocation Means of revoking an access token. Getty Images or a user can revoke an access token if suspicious activity is detected.
Client Type A 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)
PKCE Proof Key for Code Exchange (see the OAuth 2.0 PKCE RFC) for more info.
Code Verifier PKCE Requirement A cryptographically random string that is used to correlate the authorization request to the token request.
Code Challenge PKCE Requirement A challenge derived from the code verifier that is sent in the authorization request, to be verified against later.
Code Challenge Method PKCE Requirement The method that was used to derive code challenge. plain or S256

Authorization Grant Types

Authorization Grant Client Environment Entities Required
Authorization Code Web application with a server-side component which can secure the API secret API key and secret, User ID and password, code verifier, code challenge and code challenge method
Client Credentials Client application is also the resource owner. API key and secret

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://authentication.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. Wildcards are not permitted.
    • 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://authentication.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://authentication.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://authentication.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.

Example Refresh Token Request
POST https://authentication.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

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://authentication.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

Redirect URIs for Authorization grants

Authentication workflows requiring a Redirect URI (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

Read more

Technical Documentation Search