This section explains the embargoed assets feature and how you can use it in your project to control access to assets in your space.
Embargoed assets combines security best practices, endpoints, and API support to protect access to protected assets in a space. Access to asset files is controlled by short-lived, cryptographically signed asset URLs that you generate. This feature is available free of charge to all customers on the Enterprise tier.
Embargoed assets can be enabled on the space-level only; it cannot be enabled on a per-environment or per-asset level. 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 successfully be retrieved.
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.
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 means of access control.
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 on 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.
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.
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.
When enabling embargoed assets, you can select whether to protect all assets or unpublished assets only. 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.
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.
Enable embargoed assets for a selected space by contacting Support.
Implement authorization and asset URL signing logic , and ensure that your space is requesting all assets from the secure assets delivery network.
Please 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.
More details on how the feature works and how to get started using it in your project can be found here.
A list of specific terminology related to embargoed assets can be found here.
Embargoed assets API reference documentation can be found as part of: