Embargoed assets
The Embargoed assets feature allows you to control who has access to your assets. It is useful in the scenarios where you want to ensure only authorized users can access the assets in a selected space.
Use cases
Common scenarios:
intranet and extranet portals
paywalls
when you are working with sensitive assets.
NOTE: The Embargoed assets feature is only available on specific plans. Reach out to your Sales representative for more information about feature availability.
Overview
The Embargoed assets feature combines security best practices, endpoints, and API support to protect access to assets in a space. Access to asset files is controlled by short-lived, cryptographically signed asset URLs that you generate.
Important: Embargoed assets can be enabled at space level only, and not per environment or for a single asset. You can choose to protect all assets or only unpublished assets.
Once the feature is enabled, protected assets in a given space will require signed asset URLs in order to be retrieved successfully.
You have the flexibility to implement your own access control logic to protect assets by building on top of signed URLs. That means we do not provide a web app UI or API that dictates how the user’s access is authorized. You are free to decide what information you are going to use and how to evaluate whether a specific user should have access to an embargoed asset or not.
Difference between embargoed assets and regular assets
To understand what embargoed assets can do for you, it is essential to know how you retrieve assets managed in a space when not using embargoed assets.
When you retrieve asset information from the Content Management API (CMA), Content Preview API (CPA), or Content Delivery API (CDA), you receive localized asset metadata, such as the asset’s title and description, along with a public asset URL that can be used to fetch the associated asset file. Although an authentication token protects requests to all Contentful APIs, an asset file can be retrieved with no authentication if you know the public asset URL. This applies to both published and unpublished assets. This is not a problem for most users: asset URLs are random and infeasible to guess, and most asset files’ content is not confidential.
However, in some cases, such as paywalled content, corporate intranet portals, external membership portals, and others, may all benefit from extra protection. For these types of use cases, we offer embargoed assets as a means of access control.
Protecting assets using embargoed assets
Below are some examples of how embargoed assets can be used:
Reduce the risk of leaking an asset
The embargoed assets feature helps you reduce and control the risk of an asset being accessed by an unauthorized user.
Even with difficult-to-guess asset URLs, an unauthorized user may get a hold of an asset URL by accident. For example, an asset URL could be accidentally forwarded to someone who’s not supposed to access the asset. The possibility of a leak increases if you collaborate with external contributors (e.g. agencies, PR outlets, translators, etc.) to get your assets ready for publishing.
Portals
The embargoed assets feature allows you to make an asset accessible to selected users only.
Some content should only be accessible to employees only. Some content should only be accessible to a subset of those employees, perhaps based on the team they belong to. Other content should only be accessible to partners reselling your products and services. Or accessible only to users that achieved a certain membership status based on their purchasing history. Whatever your specific needs, embargoed assets can provide an adaptable solution.
Paywalls
The embargoed assets feature allows you to gate your content behind a paywall.
This is where you want to allow access to an asset only to users with a valid paid subscription. Before a user is allowed to view specific content, they need to authenticate, and the content is served only if they have an available content quota. This is a different flavor of the portal use case described above.
Keep reading to learn how the embargoed assets feature works and how you can use the feature to enable any of the scenarios outlined above.
Using embargoed assets
When enabling embargoed assets, you can select whether to protect all assets or only unpublished. Learn more about different types of protection here.
Once you enable the feature, asset URLs returned by the CMA, CDA, or CPA will need to be cryptographically signed before use. Signing is accomplished by first fetching a short-lived (valid for up to 48h) asset key from Contentful’s API. This asset key can be used to sign any number of asset URLs within a particular space until its expiry, and each signed URL can have an independent lifespan. A specific asset file is accessible to anyone who has a correctly signed URL until that URL has expired.
You are responsible for implementing authorization logic to decide whether a specific user should or should not have access to the asset. Contentful does not limit you in any way as to what information and how it can be used for this purpose.
Getting started with embargoed assets
As a space administrator, you can configure embargoed assets.
Here is a high-level overview of what you need to do to start benefiting from the feature:
Select a protection mode that best fits your needs.
From the space Settings drop-down menu, select "Embargoed assets". This menu item is only visible to space administrators.
On the settings screen, click "Get started" to enable embargoed assets in "preparation mode". All of your assets will remain publicly accessible, but you can begin using embargoed assets APIs.
Implement authorization and asset URL signing logic while still in preparation mode, and ensure that your space is requesting all assets from the secure assets delivery network.
Once you are certain everything functions as expected, change the protection mode in embargoed assets setting to either "all assets protected" or "unpublished assets protected" mode, depending on your needs.
NOTE: You can use secure asset URLs just like you do standard asset URLs. You can download the asset, or you can embed the asset. You just need to keep in mind the expiration period and how that may influence your specific use case.
For more information on how the feature works and how to get started, see the developer documentation.
A list of specific terminology related to embargoed assets can be found here.
Next steps
Embargoed assets API reference documentation can be found as part of: