Unsplash API Authentication: Methods and Security (2026)

Authentication overview

Unsplash API implements an authentication approach centered on OAuth 2.0 for actions requiring user authorization, such as liking photos or managing user collections. For public data access where user context is not required, API keys (referred to as Access Keys in Unsplash documentation) serve as a simpler method for application identification and rate limiting. This dual-method strategy allows developers to choose the appropriate security context for their application's interactions with Unsplash content. All API communication is secured via HTTPS to protect data in transit, aligning with standard web security practices.

Integrating with the Unsplash API involves registering an application to receive the necessary credentials. These credentials, whether OAuth 2.0 client IDs and secrets or an API Access Key, are essential for making authenticated requests and adhering to rate limits. The API's Unsplash API reference details the specific requirements for each endpoint, indicating when OAuth 2.0 is mandatory versus when an API key suffices. Understanding these distinctions is crucial for building secure and functional applications.

Supported authentication methods

The Unsplash API supports two primary authentication methods, each designed for different use cases and offering varying levels of security and access control.

• OAuth 2.0: This protocol is recommended for applications that interact with user-specific data or perform actions on behalf of a user. OAuth 2.0 enables delegated authorization, allowing an application to access a user's Unsplash account with their permission, without ever handling their login credentials directly. The OAuth 2.0 specification is an open standard for access delegation, commonly used across web APIs. Unsplash API specifically utilizes the Authorization Code grant type, suitable for web applications, and also supports implicit and client credentials grants for other scenarios.
• API Key (Access Key): For read-only access to public Unsplash data, such as searching photos or fetching public collections, an API key is a simpler authentication method. This key identifies your application and is primarily used for rate limiting. It grants access to public endpoints without requiring user authorization. While convenient, API keys should be handled with care as their compromise could lead to unauthorized usage of your application's quota.

The choice between OAuth 2.0 and an API key depends on the desired functionality and the scope of access required by your application. For instance, an application displaying trending photos might only need an API key, whereas an application allowing users to like photos or view their private collections would necessitate OAuth 2.0.

Getting your credentials

To obtain the necessary credentials for Unsplash API authentication, you must first register your application on the Unsplash Developer website. This process involves creating a new application and providing details such as the application name, description, and an authorized redirect URI if you plan to use OAuth 2.0. The redirect URI is where Unsplash will send the user back after they authorize your application, along with an authorization code.

Upon successful registration, Unsplash will provide you with:

• Access Key (API Key): This key is immediately available and can be used for public, read-only API requests. It acts as your application's identifier for rate limiting purposes.
• Secret Key (Client Secret): This key is provided alongside your Access Key and is crucial for OAuth 2.0 flows. It must be kept confidential and never exposed in client-side code.

For OAuth 2.0 implementation, you will also need to configure your application's redirect URI(s) within the Unsplash developer dashboard. This step is critical for the secure exchange of authorization codes for access tokens, as outlined in the Unsplash API authentication guide. Without a correctly configured redirect URI, the OAuth 2.0 flow cannot complete successfully.

It is important to store your Secret Key securely, typically in environment variables or a secure configuration management system, rather than hardcoding it directly into your application's source code. This practice minimizes the risk of unauthorized access if your code repository is compromised.

Authenticated request example

This example demonstrates how to make an authenticated request using an API key to fetch a random photo from the Unsplash API. For OAuth 2.0 examples, which involve multiple steps (authorization, token exchange, then API calls), refer to the Unsplash OAuth flow documentation.

Example using an Access Key (API Key):

First, obtain your Access Key from your Unsplash developer applications page.

curl -X GET \
  'https://api.unsplash.com/photos/random' \
  -H 'Authorization: Client-ID YOUR_ACCESS_KEY'

In this cURL command:

• YOUR_ACCESS_KEY should be replaced with the actual Access Key provided by Unsplash for your registered application.
• The Authorization: Client-ID header is the standard way to pass the Access Key for public endpoints.
• https://api.unsplash.com/photos/random is the endpoint for fetching a random photo.

Example using an OAuth 2.0 Access Token (after successful OAuth flow):

Once you have successfully completed the OAuth 2.0 authorization flow and obtained an access_token, you can use it to make requests that require user authentication. This token typically has a limited lifespan and may need to be refreshed using a refresh_token.

curl -X GET \
  'https://api.unsplash.com/me' \
  -H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN'

In this cURL command:

• YOUR_OAUTH_ACCESS_TOKEN should be replaced with the access token obtained from the OAuth 2.0 flow.
• The Authorization: Bearer header is the standard for passing OAuth 2.0 access tokens. This method is consistent with the OAuth 2.0 Bearer Token Usage specification.
• https://api.unsplash.com/me is an example endpoint that requires user authentication to retrieve the current user's profile.

Security best practices

Adhering to security best practices is essential when integrating with the Unsplash API to protect both your application and user data. The following guidelines help minimize risks associated with credential management and API interactions.

Credential Management

• Keep Secret Keys confidential: Your OAuth 2.0 Secret Key (Client Secret) and any API keys should never be exposed in client-side code (e.g., JavaScript in a browser) or committed directly into public source code repositories. Store them in environment variables, a secure configuration service, or a secrets manager.
• Rotate credentials regularly: Periodically rotate your API keys and OAuth 2.0 client secrets. This reduces the impact if a credential is ever compromised, limiting the window of vulnerability.
• Least privilege access: Only request the necessary OAuth scopes from users. Do not ask for broader permissions than your application truly needs. This minimizes the risk in case your application's access token is compromised.
• Secure storage for access tokens: When storing OAuth access tokens and refresh tokens, ensure they are encrypted at rest and accessed only by authorized backend services. Avoid storing them in local storage or cookies if your application is purely client-side, or ensure robust security measures are in place.

API Interaction Security

• Always use HTTPS: The Unsplash API mandates HTTPS for all requests, ensuring that data transmitted between your application and Unsplash is encrypted and protected from eavesdropping and tampering.
• Validate redirect URIs: For OAuth 2.0, configure and strictly validate your authorized redirect URIs in the Unsplash developer dashboard. This prevents malicious actors from intercepting authorization codes by redirecting users to unauthorized domains.
• Implement state parameter in OAuth: Use the state parameter in your OAuth 2.0 authorization requests to prevent Cross-Site Request Forgery (CSRF) attacks. The state parameter should be a unique, unguessable value generated by your application for each authorization request and verified upon callback.
• Handle errors securely: Do not expose sensitive information in error messages returned to the client. Log detailed errors on your server, but provide generic, user-friendly messages to end-users.
• Rate limit awareness: Be mindful of Unsplash API's rate limits. Implement proper error handling for 429 Too Many Requests responses and consider exponential backoff strategies to avoid being blocked.

Application Security

• Regular security audits: Periodically review your application's code and infrastructure for vulnerabilities, especially those related to authentication and authorization.
• Dependency management: Keep all third-party libraries and frameworks used in your application updated to their latest secure versions to mitigate known vulnerabilities.