Contentful API Integration: Configuring CDA, CMA, CPA

Confusion among the three Contentful HTTP APIs is the most common reason why draft entries appear in production or editors' changes fail to save. Over more than 5 years of work, our engineers have seen dozens of projects where a single wrong token cost hours of debugging. Let's clarify how to distinguish between Delivery, Management, and Preview APIs, and provide ready-made configs for Next.js and Node.js.

How to distinguish the three Contentful APIs?

Content Delivery API (CDA) — read-only access to published content. Base URL: https://cdn.contentful.com. Token: delivery access token (read-only, can be committed to environment variables). Responses are cached on CDN — this yields TTFB under 100 ms when configured properly, which is 5x faster than without caching. Content Preview API (CPA) — read-only, but including drafts (unpublished entries). Base URL: https://preview.contentful.com. Token: preview access token. Used in Next.js Draft Mode / preview mode. Never use this token in production — otherwise the public will see unfinished articles. Content Management API (CMA) — full CRUD. Base URL: https://api.contentful.com. Token: personal access token or OAuth. Never used on the frontend. Only in backend scripts, admin panels, and CI/CD.

How to choose the token for each environment?

In .env.local, always store three keys: CONTENTFUL_ACCESS_TOKEN_DELIVERY, CONTENTFUL_ACCESS_TOKEN_PREVIEW, and CONTENTFUL_MANAGEMENT_TOKEN. For production, use only Delivery. For staging — Preview. Management — only in local scripts and CI.

To avoid confusion, create separate .env.production and .env.staging files. In CI/CD, configure automatic token substitution based on branch name. This reduces human error risk. Practice shows: 90% of Contentful incidents are related to incorrect tokens.

Client setup

import { createClient } from 'contentful'; // Для продакшена const deliveryClient = createClient({ space: process.env.CONTENTFUL_SPACE_ID!, accessToken: process.env.CONTENTFUL_DELIVERY_TOKEN!, }); // Для превью (Next.js Draft Mode) const previewClient = createClient({ space: process.env.CONTENTFUL_SPACE_ID!, accessToken: process.env.CONTENTFUL_PREVIEW_TOKEN!, host: 'preview.contentful.com', }); // Выбор клиента по флагу export const getClient = (preview = false) => preview ? previewClient : deliveryClient; 

Next.js Draft Mode + Preview API

// app/api/draft/route.ts import { draftMode } from 'next/headers'; import { redirect } from 'next/navigation'; export async function GET(request: Request) { const { searchParams } = new URL(request.url); const secret = searchParams.get('secret'); const slug = searchParams.get('slug'); if (secret !== process.env.CONTENTFUL_PREVIEW_SECRET) { return new Response('Invalid token', { status: 401 }); } draftMode().enable(); redirect(`/blog/${slug}`); } // В компоненте страницы import { draftMode } from 'next/headers'; export default async function BlogPost({ params }) { const { isEnabled } = draftMode(); const client = getClient(isEnabled); const entry = await client.getEntries({ content_type: 'blogPost', 'fields.slug': params.slug, }); } 

CMA: programmatic content management

import { createClient } from 'contentful-management'; const cmaClient = createClient({ accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN!, }); const space = await cmaClient.getSpace(process.env.CONTENTFUL_SPACE_ID!); const env = await space.getEnvironment('master'); // Создание записи const entry = await env.createEntry('blogPost', { fields: { title: { 'en-US': 'New Post' }, slug: { 'en-US': 'new-post' }, }, }); // Публикация await entry.publish(); 

Why is Preview API critical for editors?

Without Preview API, an editor cannot preview how an article will look before publishing. They are forced to publish "blind" and roll back errors. On one project, we implemented CPA and reduced content proofreading time by 40%: editors saw drafts directly on the staging domain via Draft Mode. Compared to manual export, Preview API reduces publishing errors by 3x.

Optimizing Contentful API requests

To avoid N+1 queries and reduce latency, use select and limit parameters: client.getEntries({ select: 'fields.title,fields.slug', limit: 50 }). For Delivery API, enable CDN caching (e.g., Cloudflare) with a TTL of up to 1 hour — this will boost LCP by 20%. For frequent queries, use ISR revalidation in Next.js. When working with drafts via Draft Mode, hydration mismatch may occur — solution: synchronize the token and space on server and client.

Environment configuration table

On a 401 error, check that the token matches the environment and has not expired. For CMA, ensure the Personal Access Token has permissions for the required space.

Turnkey setup process

1. Analysis: gather requirements for locales, environments, content types.
2. Design: define token schema, middleware for API selection.
3. Implementation: write isolated clients for CDA, CPA, CMA.
4. Testing: verify each token works in its environment, no draft leakage to production.
5. Deployment: configure CI/CD for automatic token replacement during promotion.

Official Contentful Delivery API documentation.

Timeline: from 3 to 7 days depending on project complexity. Cost is calculated individually after auditing current integration. Content proofreading time savings — up to 40%.

What is included in the work

• Source code for the client module for CDA, CPA, CMA (TypeScript)
• Documentation on environment variables and tokens
• Draft Mode setup for editors
• Migration of existing queries to the new client
• Team training (1 hour online)
• Support for one month after integration