How to Connect Contentful to Univaultport

Contentful is a headless CMS with a separate management API for content operations. Univaultport uses that CMA (Content Management API) for both reading and writing assets — the same path Contentful's web UI uses internally. Setup is two pieces of information: a Space ID and a CMA token.

Step 1 — Find your Space ID

Sign in at app.contentful.com and pick the space you'll migrate to or from.

Open Settings → General settings. The Space ID is a short alphanumeric string near the top of the page:

Space name:  Acme Marketing
Space ID:    abc1d2e3f4g5            ← paste this

The Space ID is not the human-readable name. Copy the actual ID value.

Step 2 — Generate a Personal Access Token (CMA)

Click your profile picture (top-right) → Account settings → CMA tokens (or visit it directly at app.contentful.com/account/profile/cma_tokens).

1. 1

   Create Personal Access Token

   Click the green button. Name it something specific like asset-migrator-prod so you'll recognize it later.
2. 2

   Generate

   A token string appears starting with CFPAT-…. Copy it now — Contentful only shows it once. If you lose it, you'll have to revoke and create a new one.

For tighter scoping, see Step 6 below — Contentful also supports per-space, per-role tokens via the Organization → Access tokens flow on paid plans.

Step 3 — Verify the role on the space

Your CMA token does whatever role you have on the space allows. For migrations Univaultport needs to create, process, publish, and delete assets. The minimum role is:

For destination use, Editor is the minimum. Developer is recommended because you may want to delete obsolete source assets after a migration. Owner/Admin works but is broader than needed.

Check your role under Settings → Users.

Step 4 — Paste credentials into Univaultport

In the connector wizard:

1. 1

   Space ID

   Paste the alphanumeric Space ID from Step 1.
2. 2

   CMA Token

   Paste the CFPAT-… token from Step 2.
3. 3

   Environment (optional)

   Leave blank to use master, or specify another environment like staging if you want to test the migration in a non-production environment first.

Hit Save & test. Univaultport probes the environment with getAssets({ limit: 1 }) — this confirms both the token and CMA scope work for actual migration operations, not just for reading space metadata.

What happens during an upload to Contentful

Contentful's asset model is more involved than plain object storage. Every upload goes through a 5-step pipeline that Univaultport runs for you automatically:

1. POST  /uploads                  — stream file bytes, get an upload sys.id
2. POST  /assets                   — create draft asset linked to the upload
3. PUT   /assets/{id}/files/{loc}  — tell Contentful to process the upload
                                     (blocks until CDN ingest completes)
4. PUT   /assets/{id}/published    — publish so the Delivery API can serve it
5. ← done — destination URL is the contentful.com CDN

The whole flow happens per asset. Steps 1 and 3 are the slow ones — Contentful pulls the file from its upload buffer through its image processor and onto the CDN. For images this is typically 2-5 seconds; for video, much longer.

Locales

Every Contentful asset is locale-scoped — its filename, title, and file URL all exist per locale (e.g. en-US, de-DE). Univaultport picks up the default locale from the environment automatically (you can see which one in the connection test message) and uses it for all reads and writes.

If you need to migrate the same asset across multiple locales, run separate migrations after switching the environment's default locale, or contact us — multi-locale support is straightforward to add.

Environments

Environments are Contentful's branching feature. They're useful for migrations because you can:

1. Create a migration-test environment from your master baseline
2. Point Univaultport's destination connector at it
3. Verify the migration looks right
4. Either merge the environment back to master or run the real migration against master

This is the safest pattern for production migrations. The free tier limits you to 1 non-master environment; paid tiers allow more.

Rate limits

Contentful enforces a 7 requests per second limit per CMA token on the free Community tier. Higher tiers raise this:

Each asset migration uses ~5 API calls (upload + create + process + publish + verify), so the free tier processes roughly 1 asset per second sustained. For larger libraries, expect either a paid plan or a longer migration window.

Univaultport's worker automatically retries with exponential backoff on 429 errors — you don't need to throttle manually.

Common errors

Auto-publish behavior

Univaultport publishes every uploaded asset automatically. This is the right default because:

• Unpublished assets aren't accessible via the Content Delivery API (the public API everything consumes)
• Web/mobile clients querying Contentful won't see them
• "Draft only" workflows are rare in DAM-style migrations

If you specifically need draft-only migrations, let us know — it's a one-line option flag to expose.

Next steps

With Contentful connected, common patterns are:

• Cloudinary → Contentful for moving a DAM library into a CMS
• Contentful → S3 / GCS for backups or moving the canonical store
• Contentful → Contentful across spaces (e.g. brand consolidation after an acquisition)

Folder hierarchy doesn't apply — Contentful's asset library is flat. The wizard's destFolderMode: 'new' option is silently ignored for Contentful destinations.