Contentful Images Authentication: Access & Security (2026)

Authentication overview

Contentful Images leverages the existing authentication mechanisms of the broader Contentful platform. This means that access to Contentful Images, including fetching and transforming assets, is governed by the same API keys used for accessing Contentful's Content Delivery API (CDA) and Content Preview API (CPA). The Contentful Images API is primarily used for requesting dynamic transformations of image assets stored within a Contentful space, rather than for direct uploads or modifications of the assets themselves, which are handled by the Content Management API (CMA), requiring different authentication.

For most image delivery and transformation use cases, the Contentful Images API functions without explicit authentication headers in the request URL itself, when retrieving publicly available assets. However, authorization is implicitly tied to the space and environment where the assets reside. For private assets or scenarios requiring greater control, Contentful provides mechanisms to secure access, often by utilizing signed URLs generated on the server side using your API keys, preventing unauthorized access to specific image transformations.

The primary design principle is to enable seamless and performant image delivery within content-driven applications while maintaining appropriate security boundaries. Developers interact with the Contentful Images API by constructing URLs with various parameters for resizing, cropping, quality adjustment, and format conversion. The system then processes and delivers the image, often from a global Content Delivery Network (CDN).

Supported authentication methods

Contentful Images primarily relies on API keys for authentication and authorization. These keys are generated within the Contentful web application and grant either read-only access to published content (Delivery API key) or access to draft content (Preview API key). The choice of key depends on whether the application requires access to published or pre-published assets through the Images API.

The Contentful Images API does not typically require an authorization header for requests to images.contentful.com for publicly accessible assets. Instead, access is implicitly managed through the Contentful Delivery API (CDA) or Content Preview API (CPA) when retrieving asset URLs. The asset URLs themselves contain the necessary space ID and asset ID to identify the image within your Contentful space. For assets configured as private, or for specific security requirements, Contentful supports generating signed URLs for secure asset delivery.

API Key Types

• Delivery API Key: Provides read-only access to published content and assets. This is the most common key used for production applications serving live content. It is typically associated with a specific Contentful Space ID and Environment ID.
• Preview API Key: Provides read-only access to both published and draft content and assets. This key is primarily used during development and content staging to view content before it's live.

Authentication Methods Summary

Getting your credentials

To obtain the necessary API keys for Contentful Images, you must access your Contentful space within the Contentful web application. The process involves creating an API key that grants access to your content delivery or preview environments.

Steps to obtain Contentful API keys:

1. Log In to Contentful: Navigate to the Contentful web application and log in to your account.
2. Select Your Space: Choose the specific Contentful space that contains the images you intend to manage.
3. Access API Keys: In the Contentful web app, go to Settings > API keys.
4. Create a New API Key: Click the Add API key button.
5. Configure Key Settings:
   • Name: Provide a descriptive name for your API key (e.g., "Website Production Images").
   • Content Delivery API: By default, Contentful generates a Delivery API access token. This token is what you will use for fetching published images. Note down the Space ID and the Content Delivery API - Access Token.
   • Content Preview API: If you need access to draft images, you will also find a Content Preview API - Access Token on the same page.
6. Save the Key: Once created, Contentful will display your Space ID and access tokens. Copy these values immediately, as the access token may not be fully visible again after navigating away from the page for security reasons.

For more detailed instructions, refer to the official Contentful Content Delivery API authentication documentation.

Authenticated request example

While the Contentful Images API does not typically require an explicit authentication header in the URL for public assets, the URL structure itself includes the necessary identifiers (space ID, asset ID) that implicitly link the request to your Contentful space. For private assets, or scenarios requiring explicit signing, you would generate a signed URL on your server-side application.

Example of a Public Image Request (Implicit Authentication)

This example demonstrates how to request a transformed image from Contentful Images. The space_id and asset_id are part of the URL path, effectively linking the request to your Contentful account without requiring a separate API key as a query parameter for publicly accessible images.

GET https://images.contentful.com/YOUR_SPACE_ID/YOUR_ASSET_ID/YOUR_IMAGE_FILENAME.jpg?w=400&h=300&fit=fill&fm=webp

Replace YOUR_SPACE_ID with your actual Contentful Space ID and YOUR_ASSET_ID with the ID of the image asset you wish to retrieve. The YOUR_IMAGE_FILENAME.jpg is the original filename of the asset. The query parameters (w, h, fit, fm) specify the desired transformations.

Example of a Signed URL Request (Explicit Authentication for Private Assets)

For private assets, you must generate a signed URL on your backend. This involves creating a hash signature using your Contentful API key (which is kept secret on the server) and including it in the image URL. This prevents unauthorized access to private images. The Contentful Images API documentation provides a detailed guide on generating signed URLs, which typically involves:

1. Concatenating the image URL (without the signature) with your API key.
2. Hashing the concatenated string using a secure algorithm (e.g., HMAC-SHA256).
3. Encoding the hash and appending it to the URL as a sig parameter.

The server-side generation ensures your API key is never exposed client-side. This approach is similar to how other cloud providers handle secure content delivery, such as Google Cloud Storage Signed URLs, by providing time-limited access tokens in the URL itself.

Security best practices

Securing your Contentful Images implementation involves protecting your API keys and carefully managing asset access. Adhering to these best practices helps prevent unauthorized usage and maintains data integrity.

1. Protect API Keys

• Server-side usage for sensitive operations: While Contentful Delivery API keys are read-only and designed for client-side use, avoid hardcoding them directly into public client-side code where possible. If generating signed URLs, this process must occur on a secure backend server to prevent exposure of your secret API key.
• Environment Variables: Store API keys in environment variables on your server or build system, rather than directly in your codebase. This prevents keys from being committed to version control systems like Git.
• Restrict Permissions: When creating API keys, ensure they only have the necessary permissions. For Contentful Images, Delivery API keys provide read-only access, which is suitable for client-side image fetching.

2. Regularly Rotate API Keys

• Scheduled Rotation: Implement a schedule to periodically rotate your Contentful API keys (e.g., every 90-180 days). This minimizes the impact of a compromised key, should one occur.
• Immediate Rotation on Compromise: If you suspect an API key has been compromised, revoke it immediately within the Contentful web app and replace it with a new one.

3. Leverage Signed URLs for Private Assets

• Server-Side Generation: For any images that should not be publicly accessible, generate signed URLs on your backend server. This involves hashing the request parameters with your API key (secret) and appending the resulting signature to the URL. This ensures that only requests with a valid, time-limited signature can access the private asset.
• Short Expiration Times: Set short expiration times for signed URLs to limit the window of opportunity for unauthorized access, typically minutes to a few hours depending on the use case.

4. Implement Content Security Policy (CSP)

• Restrict Image Sources: Configure your website's Content Security Policy to only allow images from trusted domains, including images.contentful.com. This helps mitigate risks from cross-site scripting (XSS) attacks by preventing browsers from loading unauthorized images. For example: img-src 'self' images.contentful.com;

5. Monitor Usage and Logs

• Anomaly Detection: Regularly monitor your Contentful usage statistics and application logs for unusual patterns of image requests. Spikes in requests or requests from unexpected IP addresses could indicate unauthorized activity.

6. Secure Your Contentful Account

• Strong Passwords and MFA: Enforce strong, unique passwords for all Contentful user accounts and enable multi-factor authentication (MFA) to add an extra layer of security.
• Role-Based Access Control (RBAC): Use Contentful's RBAC features to grant users only the minimum necessary permissions within your Contentful space, limiting who can create, view, or manage API keys.