Skip to main content

Contentful

Headless CMS: agents read and manage content types, entries and assets through the Content Management API.

Connect it with: API key. Contentful's own documentation: https://www.contentful.com/developers/docs/references/authentication/.

What agents can do​

Connect Contentful so the agents working your tasks can reach it. With it connected, they can:

  • Create, update and publish entries and assets through the Content Management API.
  • Read and change content models (content types and their fields), for example to add a field a feature needs.
  • Manage environments and locales, such as copying content between a sandbox and master.
  • Audit content: find entries missing fields, broken references or untranslated locales.

Before you start​

  • A Contentful account with access to the space or spaces agents should work in.
  • A role in those spaces that allows the changes agents should make: a personal access token acts with all of your own permissions.
  • A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.

Connect with Contentful​

Jaah connects to Contentful with an API key, not with a sign-in button.

Connect with an API key​

Find each value first:

  • Personal access token: In Contentful, open the cog menu (Settings) > CMA tokens, select Create personal access token, name it Jaah, pick an expiry and select Generate. Copy the token (it starts with CFPAT-) - Contentful shows it once.
  • Space ID (optional): Optional: the space agents should work in by default. In Contentful open Settings > General settings; the Space ID is listed there.

Then add it to Jaah:

  1. In Jaah, open Secrets, select New, and pick the Contentful card.
  2. Name the secret and choose who can use it.
  3. Fill in Personal access token, Space ID.
  4. Select Save. Jaah tests the secret straight away (see Test the connection).

Jaah encrypts what you type and never shows it again — not to you, and not to an admin.

Use your own OAuth app​

Not used: Jaah connects to Contentful with an API key, not through an OAuth app.

Test the connection​

Select Test on the secret. Jaah calls Contentful's API once (GET https://api.contentful.com/users/me) with the stored values, and shows who it answered as, or which value Contentful refused and the status it answered. Jaah also tests automatically when you save or reconnect.

The last result and its time stay on the secret's page, so you can see whether it still works without testing again.

Who can use it​

Every secret has an owner, and the owner decides who can use it:

  • Personal — only your own tasks can use it. This is the default.
  • Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
  • Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.

More on owners and access: How secrets work.

Use it in an agent session​

An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:

  • org/<name> for an organization secret,
  • projects/<project>/<name> for one attached to a project,
  • me/<name> for your personal one.

A key connection hands the agent its fields: access_token, space_id.

Tell the agent in your task description which secret to use, for example “use the Contentful secret org/contentful”.

Manage, rotate or disconnect​

Everything is on the secret's page under Secrets:

  • Rotate a key: create a new key at the vendor first, then select Replace on the secret and paste it. Revoke the old key at Contentful once the test passes. Steps: Replace or delete a secret.
  • Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at Contentful's side too, revoke or delete the key at Contentful.

Limitations​

  • A personal access token acts as you across every space and organization you can reach; Contentful offers no narrower scope for it, so connect a dedicated user when you want agents limited to one space.
  • The token expires on the date you chose when creating it; create a new one and replace the secret before then.
  • Spaces hosted in Contentful's EU data region are reached at api.eu.contentful.com, which this integration does not test against yet; the test checks the default region.
  • The Content Delivery and Preview APIs use separate space-level API keys (Settings > API keys), which are not part of this integration.
  • Agents can do only what the connected Contentful account allows.

Troubleshooting​

Test says Contentful rejected the personal access token (401)

The token was mistyped, revoked or has expired. In Contentful open Settings > CMA tokens, check its status and expiry, create a new one if needed, and select Replace on the secret in Jaah.

The test passes, but an agent gets 404 or 403 for a space

The token's user is not a member of that space or its role cannot do the change. In Contentful open the space's Settings > Users and give the user a suitable role, or check the Space ID in the agent's task.

An agent's requests fail with 429 Too Many Requests

Contentful rate-limits the Content Management API per space (around 7 requests a second on most plans). Ask the agent to batch its changes or pause between them; nothing is wrong with the connection.

Still stuck? Select Test and read the result: it names the value Contentful refused and the status it answered.

FAQ​

Can I use a Content Delivery API key instead?

No. Delivery and Preview keys only read published content of one space; this integration needs a personal access token for the Content Management API so agents can make changes.

How do I revoke Jaah's access in Contentful?

Open Settings > CMA tokens and select Revoke next to the token you created for Jaah. Agents lose access on their next call.

Can Jaah or an admin see the key or token?

No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.

Can I connect more than one Contentful account?

Yes. Add one secret per account, each with its own name, and tell the agent which one to use.