Skip to main content

Contentful — Authentication

B
Written by Ben Keeling

How to create a read-only Contentful Content Delivery API key, add it to Medialake with your space ID, and understand exactly what access it grants.



​

What to expect

Contentful is connected with a space ID and a Content Delivery API access token. There is no Contentful sign-in or consent screen when you connect: a Medialake administrator saves the space ID and token once as an access key, and Medialake authenticates to Contentful in the background from then on.

Each connection covers one space. To sync several spaces, save one access key per space and connect each one separately. Each space appears in Medialake as its own account, named after the space.

The Content Delivery API is Contentful's read-only API for published content. We follow the principle of least privilege: a delivery token can read published content but can never change it. Medialake reads the published images, videos, and PDFs in the space's master environment, along with their details and tags. It does not create, edit, publish, archive, or delete anything in Contentful.

 Administrators                Medialake                  Contentful
      │  create a Content          │                           │
      │  Delivery API key for      │                           │
      │  the space                 │                           │
      │───────────────────────────────────────────────────────▶│
      │  save space ID + token     │                           │
      │  as an access key          │                           │
      │───────────────────────────▶│                           │
      │                            │                           │
 Team member                       │                           │
      │  connect with the key      │  look up the space        │
      │───────────────────────────▶│──────────────────────────▶│
      │  choose Images, Videos     │  read published assets    │
      │  and/or PDFs               │                           │
      │───────────────────────────▶│──────────────────────────▶│


​

Before you begin

You will need:

  • A Contentful account that can create API keys in the space you want to sync

  • Administrator privileges in Medialake, to save the access key

Medialake connects to Contentful's standard Content Delivery API at https://cdn.contentful.com. Spaces that use Contentful's EU data residency add-on are served from a separate EU endpoint and cannot be connected.

>Keep the token private. A delivery token is read-only, but anyone who has it and the space ID can read all published content in the environments it covers. Store it in an approved password manager or secret-management system. Do not email it, paste it into a support ticket, or commit it to source control. Medialake stores the token encrypted and never shows it again after you save it.


​

Step 1: Create a Content Delivery API key in Contentful

We recommend a key used only by Medialake, so you can revoke it without affecting your website or other integrations.

  1. In Contentful, open the space you want to sync.

  2. Go to Settings → API keys.

  3. Select Add API key.

  4. Give the key a name that says where it is used, for example Medialake sync.

  5. Make sure the key has access to the master environment. Medialake reads assets from master only, so the key does not need access to any other environment.

  6. Save the key.

  7. Copy the Space ID and the Content Delivery API - access token.

Use the Content Delivery API token only. Contentful uses separate tokens for each of its APIs, and Medialake calls only the Content Delivery API, so do not use the Content Preview API token or a Content Management API (CMA) token.

You can also find the space ID under Settings → General settings.


​

Step 2: Add the space ID and token to Medialake

You need administrator privileges in Medialake for this step.

  1. Open Administration → Integrations from the sidebar.

  2. Open the Contentful integration.

  3. In the Access Keys section, click Create New Setting.

  4. In the New access key panel, enter a Name that identifies the space, for example Contentful website space. The name is shown in the access key list and next to every account that connects with it.

  5. Under Credentials, fill in:

- Contentful space ID (Settings → General settings): the space ID from Step 1.

- Content Delivery API access token for this space (Settings → API keys): the delivery token from Step 1.

  1. Under Who can use it?, choose the teams whose members can connect Contentful with this key, or make it available to all teams.

  2. Click Save access key.

Medialake checks the space ID when you save: it must contain only lowercase letters and numbers, with no spaces.

An access key cannot be edited after it is saved. To change the token later, save a new access key and connect with it, as described under Staying connected below.


​

Step 3: Connect Contentful and choose what to sync

Any team member who is allowed to connect sources can do this, as long as the access key is available to their team.

  1. Open Connections → Catalogue from the side menu.

  2. Find Contentful and click Connect.

  3. Under Access key, select the key for the space you want to sync.

  4. Optionally, click Test to check the space ID and token with Contentful before connecting.

  5. Click Connect.

There is no Contentful login screen. Medialake looks up the space with the token and adds the account under the space's name.

Next, choose what to sync. A Contentful space has no folders, so Medialake offers each asset type as one: Images, Videos, and PDFs. Select the types you want, and each one syncs on its own. Only published assets in the master environment are synced; drafts, archived assets, and files whose type Medialake does not support are skipped.


​

Limiting what Medialake can access

Contentful gives you three controls, and enforces all of them:

  • The token type. A Content Delivery API token is read-only and only sees published content.

  • The space. Each key belongs to one space, so the token cannot reach your other spaces.

  • The key's environments. Give the key access to master only, the one environment Medialake reads.

A delivery token can read all published content in its environments, entries as well as assets. Medialake only requests assets and the space's tags.


​

What Medialake can and cannot do

With the setup above, Medialake can:

  • Read the space's name and ID

  • List the published images, videos, and PDFs in the master environment

  • Read asset details such as titles, descriptions, file names, content types, sizes, image dimensions, dates, and tags

  • Retrieve image thumbnails

  • Download the files of the asset types you select

Medialake cannot:

  • See drafts, unpublished changes, or archived assets

  • Access other spaces, or environments the key has no access to

  • Create, edit, publish, archive, or delete entries or assets

  • See Contentful users, passwords, or space settings


​

Staying connected

Medialake sends the saved token with every request. There is no token to refresh and nothing for anyone to re-approve.

If Contentful stops accepting the token, for example because the API key was deleted, the account stops syncing and shows a Service Disconnected warning in Medialake. To restore it, create a new key (Step 1), save it as a new access key (Step 2), and connect again with it (Step 3). Connecting the same space again in the same team updates the existing account instead of adding a second one. If the problem was on the Contentful side and has been fixed, click Check connection on the warning to test the saved token again.


​

Revoking access

To stop Medialake from reaching Contentful:

  • In Contentful: delete the API key created for Medialake under Settings → API keys. Your other keys keep working.

  • In Medialake: remove the Contentful account if it should no longer sync. Once no account uses the access key, delete it from the integration's Access Keys section. Medialake will not delete an access key that a connected account still uses.


​

Troubleshooting

Symptom

What to check

"The Contentful space ID (Settings → General settings) format is invalid." when saving

The space ID must contain only lowercase letters and numbers. Copy it again from Settings → API keys or Settings → General settings, without spaces.

"A setting with this title already exists in the group. Choose a different title." when saving

Another Contentful access key already uses that Name. Choose a different name.

Test reports "The provider rejected these credentials."

The token is wrong, was copied incompletely, or is not a Content Delivery API token. Copy the Content Delivery API - access token again and save it as a new access key.

Test reports "Contentful couldn't find this space for this access token. Check the space ID."

The space ID is wrong, or belongs to a different space from the token. This also appears for spaces that use Contentful's EU data residency, which Medialake cannot connect.

Test reports "These credentials look right, but the provider couldn't confirm them just now."

Contentful could not be reached or returned a temporary error. Try again in a few minutes.

An Incorrect Credentials. page appears after clicking Connect

Medialake could not look up the space with this token. Run Test on the access key and correct the space ID or token.

The account connects, but nothing syncs

Check that the API key has access to the master environment, and that the space has published assets of the types you selected.

Some assets do not appear

Only published assets are synced. Drafts and archived assets are not visible to a delivery token, and file types Medialake does not support are skipped.

You need to sync a second space

Create a key in that space and save it as a separate access key, then connect it as a separate account.

The account shows Service Disconnected

Contentful stopped accepting the token. See Staying connected above.

If the issue continues, contact [email protected] with the space name, the name of the access key, and the error message. Do not include the access token.


​

Further reading


Questions about connecting Contentful? Contact [email protected].

Did this answer your question?