Storyblok
Headless CMS: agents read and manage stories, components and assets through the Management API.
Connect it with: API key. Storyblok's own documentation: https://www.storyblok.com/docs/api/management/getting-started/authentication.
What agents can do
Connect Storyblok so the agents working your tasks can reach it. With it connected, they can:
- Create, edit and publish stories, including their nested blocks and translations.
- Read and change component schemas, for example to add a field a new page section needs.
- Upload and organize assets in the asset library.
- Audit a space: find unpublished changes, empty fields or missing translations.
Before you start
- A Storyblok account with access to the spaces agents should work in.
- The region your spaces are hosted in (EU, US, Canada or Australia).
- A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.
Connect with Storyblok
Jaah connects to Storyblok with an API key, not with a sign-in button.
Connect with an API key
Find each value first:
- Personal access token: In Storyblok, open My account > Account settings > Personal access tokens and select Generate New Token. Name it Jaah, set an expiry, choose the spaces it may reach and its scopes, then generate and copy it - Storyblok shows it once.
- API host (by region): Type the host name for the region your spaces are hosted in: mapi for the EU (the default), api-us for the United States, api-ca for Canada, api-ap for Australia - exactly those letters, not the region name. A space's region is shown in its Settings > General.
Then add it to Jaah:
- In Jaah, open Secrets, select New, and pick the Storyblok card.
- Name the secret and choose who can use it.
- Fill in Personal access token, API host (by region).
- 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 Storyblok with an API key, not through an OAuth app.
Test the connection
Select Test on the secret. Jaah calls Storyblok's API once (GET https://<API host (by region)>.storyblok.com/v1/spaces/) with the stored values, and shows whether Storyblok accepted it, or which value Storyblok 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, api_host.
Tell the agent in your task description which secret to use, for example “use the Storyblok secret org/storyblok”.
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 Storyblok 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 Storyblok's side too, revoke or delete the key at Storyblok.
Limitations
- One secret reaches one region; spaces in another region need their own secret with that region's API host.
- Spaces in Storyblok's China region are not supported.
- A personal access token acts as you, limited to the spaces and scopes chosen when it was created, and it stops working on its expiry date.
- The Content Delivery API's space tokens (preview and public) are separate and not part of this integration.
- Agents can do only what the connected Storyblok account allows.
Troubleshooting
Test says Storyblok rejected the personal access token (401)
The token was mistyped, revoked or has expired, or it is a space preview token rather than a personal access token. Generate a new one under My account > Account settings > Personal access tokens and select Replace on the secret.
The test passes but lists none of my spaces, or an agent gets 404 for a space
API host does not match the region the space is hosted in, or the token was limited to other spaces. Check the space's region in Settings > General and set API host to match (mapi, api-us, api-ca or api-ap), or generate a token that includes the space.
Test says Storyblok cannot be reached at that address
API host holds something other than mapi, api-us, api-ca or api-ap - for example the region name EU or a full URL. Enter just the host name for your region.
An agent's requests fail with 429 Too Many Requests
The Management API allows a limited number of requests per second depending on your plan. Ask the agent to batch changes or slow down; the connection itself is fine.
Still stuck? Select Test and read the result: it names the value Storyblok refused and the status it answered.
FAQ
Can I use a space's preview or public token?
No. Those tokens only read content through the Content Delivery API. Agents need a personal access token for the Management API to make changes.
How do I revoke the token in Storyblok?
Open My account > Account settings > Personal access tokens and delete the Jaah token. 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 Storyblok account?
Yes. Add one secret per account, each with its own name, and tell the agent which one to use.