Blog posts by Andre Gabriel Coetzee2026-06-22T13:31:38.0000000Zhttps://world.optimizely.com/blogs/andre-gabriel-coetzee/Optimizely WorldOptimizely Content APIs: the Setup the Docs Don't Walk You Through<p class="font-claude-response-body break-words whitespace-normal">CMS 13 is pushing things firmly in the direction of Optimizely Graph, but plenty of teams are still running on older CMS versions, or have good reasons to stick with the Content Delivery, Content Definitions, or Content Management APIs regardless of what version they're on. This guide is for those teams.</p>
<p class="font-claude-response-body break-words whitespace-normal">What follows is a step-by-step walkthrough to get any of the content APIs up and running, tested locally, and fully understood, in one place. No jumping between API reference pages, no piecing together fragments from several different resources. Just the things the documentation doesn't make obvious, learned the hard way.</p>
<hr class="border-border-200 border-t-0.5 my-3 mx-1.5" />
<h3 class="text-text-100 mt-3 -mb-1 text-[1.125rem] font-bold"><strong>The mental model first</strong></h3>
<p class="font-claude-response-body break-words whitespace-normal">Optimizely uses OpenID Connect (via a library called OpenIddict under the hood) to issue JWT bearer tokens. When you want a system to be able to call one of the content APIs, you define it as an OpenID Connect application, either in code, in the CMS Admin UI, or both. We'll cover the specifics of each in the steps below.</p>
<p class="font-claude-response-body break-words whitespace-normal">"Application" in this context is not referring to your CMS instance or front-end site, it refers to discrete client identities registered specifically for machine-to-machine communication. Your CMS can have as many of these as you need.</p>
<h4 class="text-text-100 mt-2 -mb-1 text-base font-bold"><strong>Why grant_type=client_credentials and not something else</strong></h4>
<p class="font-claude-response-body break-words whitespace-normal">OAuth 2.0 has several grant types: different flows for getting a token, each suited to a different kind of requester or use case.</p>
<p class="font-claude-response-body break-words whitespace-normal"><strong>authorization_code</strong> is for interactive users: a person clicks login, gets redirected, enters their credentials, and the app receives a token on their behalf.</p>
<p class="font-claude-response-body break-words whitespace-normal"><strong>client_credentials</strong> is for machine-to-machine communication. Your service acts as itself, not on behalf of a user. There are no redirects, it simply exchanges its credentials directly for a token.</p>
<h4 class="text-text-100 mt-2 -mb-1 text-base font-bold"><strong>Why the token endpoint is at /connect/token</strong></h4>
<p class="font-claude-response-body break-words whitespace-normal">This is OpenIddict's default endpoint path, and OpenIddict is the OpenID Connect server library Optimizely uses under the hood. Optimizely didn't invent this URL, it's baked into the library. The <strong>/api/episerver</strong> prefix in front of it is the actual Optimizely part of the route, sitting in the same legacy episerver namespace you'll see across the older API paths.</p>
<p class="font-claude-response-body break-words whitespace-normal">The flow from here is straightforward: you request an access token for one of these applications, then pass that token in subsequent requests to the content APIs. Importantly, the access rights you configure in the CMS are tied to the application identity itself, so when a request comes in using that token, content access is evaluated against whatever permissions that application has been granted.</p>
<p class="font-claude-response-body break-words whitespace-normal"><img src="/link/97584b3856524d738de8085f065eccdb.aspx" /></p>
<p class="font-claude-response-body break-words whitespace-normal"><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-6axZYk-gPv/0d7f2a7de1e85c0b2044c8e8f0f8d8592c1549a00a4746a00110d39d57f2a00ea426e35a907df27fefe33102d25f33b8158227cf15f4e51bef79f26d202ef1f636a7da0e82114cb5dc624aaddad115be213b1da5054a9af57d4bfbf223a6c0f0f6565710?fit=max&fm=webp&lossless=true" alt="image.png" /></p>
<p class="font-claude-response-body break-words whitespace-normal"><em>The Add User/Group dropdown showing the Applications section with two OpenID applications listed</em></p>
<hr class="border-border-200 border-t-0.5 my-3 mx-1.5" />
<h3 class="text-text-100 mt-3 -mb-1 text-[1.125rem] font-bold"><strong>Let's set it all up</strong></h3>
<h4 class="text-text-100 mt-2 -mb-1 text-base font-bold"><strong>Step 1: Install the required NuGet packages</strong></h4>
<div class="relative group/copy bg-bg-000/50 border-0.5 border-border-400 rounded-lg focus:outline-none focus-visible:ring-2 focus-visible:ring-accent-100">
<div class="overflow-x-auto">
<pre class="code-block__code !my-0 !rounded-lg !text-sm !leading-relaxed p-3.5"><code>dotnet add package EPiServer.OpenIDConnect
dotnet add package EPiServer.OpenIDConnect.UI # Optional</code></pre>
</div>
</div>
<p class="font-claude-response-body break-words whitespace-normal">You'll also need the API package for whichever API you're securing:</p>
<ul class="[li_&]:mb-0 [li_&]:mt-1 [li_&]:gap-1 [&:not(:last-child)_ul]:pb-1 [&:not(:last-child)_ol]:pb-1 list-disc flex flex-col gap-1 pl-8 mb-3">
<li class="font-claude-response-body whitespace-normal break-words pl-2">Content Delivery API: <strong>EPiServer.ContentDeliveryApi.Cms</strong></li>
<li class="font-claude-response-body whitespace-normal break-words pl-2">Content Management API: <strong>EPiServer.ContentManagementApi</strong></li>
<li class="font-claude-response-body whitespace-normal break-words pl-2">Content Definitions API: <strong>EPiServer.ContentDefinitionsApi</strong></li>
</ul>
<p class="font-claude-response-body break-words whitespace-normal"><strong>Version gotcha:</strong> Make sure your <strong>EPiServer.OpenIDConnect </strong>version is compatible with your CMS version. Mismatched versions are a common source of silent failures at startup.</p>
<h4 class="text-text-100 mt-2 -mb-1 text-base font-bold"> </h4>
<h4 class="text-text-100 mt-2 -mb-1 text-base font-bold"><strong>Step 2: Wire up the configuration in code</strong></h4>
<p class="font-claude-response-body break-words whitespace-normal">In your <strong>Startup.cs</strong>, you need to configure OpenID Connect and register whichever content APIs you need:</p>
<div class="relative group/copy bg-bg-000/50 border-0.5 border-border-400 rounded-lg focus:outline-none focus-visible:ring-2 focus-visible:ring-accent-100">
<div class="overflow-x-auto">
<pre class="code-block__code !my-0 !rounded-lg !text-sm !leading-relaxed p-3.5"><code>public void ConfigureServices(IServiceCollection services)
{
// ASP.NET Identity must be configured before OpenID Connect
services.AddCmsAspNetIdentity<ApplicationUser>();
services.AddOpenIDConnect<ApplicationUser>(
useDevelopmentCertificate: _webHostingEnvironment.IsDevelopment(),
createSchema: true,
options =>
{
// Seeding an application here is optional: see note below
options.Applications.Add(new OpenIDConnectApplication
{
ClientId = "your-client-id",
ClientSecret = "your-client-secret",
Scopes =
{
"epi_content_delivery",
"epi_content_management",
"epi_content_definitions"
}
});
});
services.AddOpenIDConnectUI(); // Optional: adds the OpenID Connect panel in CMS Admin
services.AddContentDeliveryApi(OpenIDConnectOptionsDefaults.AuthenticationScheme);
services.AddContentDefinitionsApi(OpenIDConnectOptionsDefaults.AuthenticationScheme);
services.AddContentManagementApi(OpenIDConnectOptionsDefaults.AuthenticationScheme);
}</code></pre>
</div>
</div>
<p class="font-claude-response-body break-words whitespace-normal">A few things worth noting here:</p>
<ul class="[li_&]:mb-0 [li_&]:mt-1 [li_&]:gap-1 [&:not(:last-child)_ul]:pb-1 [&:not(:last-child)_ol]:pb-1 list-disc flex flex-col gap-1 pl-8 mb-3">
<li class="font-claude-response-body whitespace-normal break-words pl-2">Each API registration method accepts an authentication scheme parameter, don't leave it out. Without it, the API has no way to validate incoming Bearer tokens and will return a <strong>401</strong> regardless of whether your token is valid. Pass <strong>OpenIDConnectOptionsDefaults.AuthenticationScheme</strong> to wire them up correctly.</li>
<li class="font-claude-response-body whitespace-normal break-words pl-2"><strong>useDevelopmentCertificate </strong>: tying this to <strong>IsDevelopment() </strong>means it uses a local dev certificate in your local environment and expects a real one in production. On DXP, certificates are provided automatically via <strong>EPiServer.CloudPlatform.Cms</strong> 1.6.1 or later.</li>
<li class="font-claude-response-body whitespace-normal break-words pl-2">Scopes: each scope string controls which API that client is permitted to call, and must match the scope you pass when requesting a token. There are constants available if you'd prefer not to use raw strings: <strong>ContentDeliveryOptionsDefaults.Scope</strong>, <strong>ContentDefinitionsApiOptionsDefaults.Scope</strong>, and <strong>ContentManagementApiOptionsDefaults.Scope</strong>.</li>
<li class="font-claude-response-body whitespace-normal break-words pl-2">Seeding applications in code is optional. The <strong>options.Applications.Add(...)</strong> block pre-creates the client on startup, which is convenient for local development. If you'd rather manage clients entirely through the UI, you can omit it, that's what the <strong>AddOpenIDConnectUI()</strong> line enables. It adds an OpenID Connect section under Settings in CMS Admin where you can create and manage applications directly.</li>
</ul>
<p class="font-claude-response-body break-words whitespace-normal"><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-oki8fxiyA7/5cd57dd6794f296df6654bc4c7aa473b1171a4d8575e67bd58ded795e9c955eead6210f9123ca6f85e7f93ea9de301c69d838208b36c8325f6744862c30110e55fd837c8291ec1448d6c817c7bd3e8ff859e13f6e235447f2ac3d73256f2466a0dfb76c4?fit=max&fm=webp&lossless=true" alt="image.png" /></p>
<p class="font-claude-response-body break-words whitespace-normal"><em>The "OpenID Connect" settings panel can be seen in the screenshot above.</em></p>
<h4 class="text-text-100 mt-2 -mb-1 text-base font-bold"> </h4>
<h4 class="text-text-100 mt-2 -mb-1 text-base font-bold"><strong>Step 3: Request a token</strong></h4>
<p class="font-claude-response-body break-words whitespace-normal">Once you have an application configured, either in code or the UI, you first need to request an access token for the application before calls to any of the content APIs can be made.</p>
<p class="font-claude-response-body break-words whitespace-normal">Using curl:</p>
<div class="relative group/copy bg-bg-000/50 border-0.5 border-border-400 rounded-lg focus:outline-none focus-visible:ring-2 focus-visible:ring-accent-100">
<div class="overflow-x-auto">
<pre class="code-block__code !my-0 !rounded-lg !text-sm !leading-relaxed p-3.5"><code>curl -X POST https://your-site.com/api/episerver/connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret&scope=epi_content_management"</code></pre>
</div>
</div>
<p class="font-claude-response-body break-words whitespace-normal">Using Postman:</p>
<p class="font-claude-response-body break-words whitespace-normal"><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-gPVIKzvOJE/f7bf91e744372274b5dccfdc85dd0dbc9baa8eb91fdee7b93a4b8c26793ee8898b698a77b9c5aa805a5fc3934d04b8642cbc3a6059ffaa92136afd1eaa2eb5f17688bd706702a0fc3613ac6f7c6d74fb7898db17dbd5b35368fd65fae32753032b11c7e6?fit=max&fm=webp&lossless=true" alt="image.png" /></p>
<p class="font-claude-response-body break-words whitespace-normal">Set the request to POST, the URL to your token endpoint, and under the Body tab select <strong>x-www-form-urlencoded</strong>. Add the four key-value pairs: <strong>grant_type, client_id, client_secret, scope</strong> </p>
<p class="font-claude-response-body break-words whitespace-normal">A successful response looks like this:</p>
<div class="relative group/copy bg-bg-000/50 border-0.5 border-border-400 rounded-lg focus:outline-none focus-visible:ring-2 focus-visible:ring-accent-100">
<div class="overflow-x-auto">
<pre class="code-block__code !my-0 !rounded-lg !text-sm !leading-relaxed p-3.5"><code>{
"access_token": "eyJhbGci...",
"expires_in": 3599,
"token_type": "Bearer"
}</code></pre>
</div>
</div>
<p class="font-claude-response-body break-words whitespace-normal">Copy the <strong>access_token</strong> value, you'll use it in Step 5.</p>
<h4 class="text-text-100 mt-2 -mb-1 text-base font-bold"> </h4>
<h4 class="text-text-100 mt-2 -mb-1 text-base font-bold"><strong>Step 4: Assign CMS access rights to the client</strong></h4>
<p class="font-claude-response-body break-words whitespace-normal">This is the most commonly missed step, and it causes some of the most confusing symptoms, you have a valid token, your requests aren't getting <strong>401s</strong>, but you're getting empty results or unexpected <strong>403s</strong>.</p>
<p class="font-claude-response-body break-words whitespace-normal">The API client you created is effectively a user in the CMS. Like any user, it needs to be granted access rights to the content it's trying to read or write. There are different levels you could configure access rights, let's get into them below.</p>
<h5 class="text-text-100 mt-2 -mb-1 text-base font-bold"> </h5>
<h5 class="text-text-100 mt-2 -mb-1 text-base font-bold"><strong>Global access rights</strong></h5>
<p class="font-claude-response-body break-words whitespace-normal">Global access rights apply at the page or section level in your content tree and cascade down to every item beneath. For instance, if you want to deny a specific OpenID application Read access to a sensitive area, say, an "Admin" page or a "Members Only" section, you set the restriction at that page, and the cascade ensures every sub-page inherits the same rule automatically. You don't have to configure each one individually.</p>
<p class="font-claude-response-body break-words whitespace-normal"><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-wHVz_SRQT6/9a2b8822c3e7ca4442dfc503adbbff00f14ed9b74eedbd81d1487dec35f33061b21d46266513d0c1e8ecbc519ea9c4fe60e0db4cdf5c8676fc955aad580be95add7cc628e35c54434f4363ddf43a528a0c579d79c3413007238721d09e47b0710261574c?fit=max&fm=webp&lossless=true" alt="image.png" /><em>On this level, either all content is returned, or none of it. Either 200-OK, or 403-Forbidden</em></p>
<p class="font-claude-response-body break-words whitespace-normal"> </p>
<p class="font-claude-response-body break-words whitespace-normal">Navigate to Settings → Set Access Rights, select the page or section you want the client to access, and add it using Add User/Group. Your registered applications (from either the code or created in the CMS on the OpenID Connect settings panel) will appear under the Applications group in the dropdown.</p>
<p class="font-claude-response-body break-words whitespace-normal">Grant it the appropriate permissions: Read is sufficient for Content Delivery, while Content Management will need Read, Change, and Publish depending on what operations you need to perform. Check Apply settings for all subitems to cascade the rights down the content tree.</p>
<p class="font-claude-response-body break-words whitespace-normal"><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-G7Oqc_d9dv/65f22110078ca502ef75b1a83a1ec3652580830c21791120f685a2cfde53b42d62737429b8ba88f183d645b66eb5160468ef90752518b2e807fd94ba6fff3b580442c4c65a742453a0e8a73515650aa577db9adad1b41ccb824c0997d8618475f3621c33?fit=max&fm=webp&lossless=true" alt="image.png" /></p>
<p class="font-claude-response-body break-words whitespace-normal"><em>alloy-client application granted Read access on the Start page, cascading to all subitems.</em></p>
<p class="font-claude-response-body break-words whitespace-normal"> </p>
<p class="font-claude-response-body break-words whitespace-normal"><strong>Why this matters:</strong> Skipping this step produces one of two outcomes depending on your setup: either the API returns a <strong>403</strong> Forbidden response, or it returns content that was never actually restricted to begin with, because the Everyone group already has read access. In the latter case everything appears to be working, but your access rights configuration isn't doing anything. If you ever tighten down content permissions, your client will silently lose access.</p>
<h5 class="text-text-100 mt-2 -mb-1 text-base font-bold"> </h5>
<h5 class="text-text-100 mt-2 -mb-1 text-base font-bold"><strong>Content-level access rights (per page/block instance in the tree)</strong></h5>
<p class="font-claude-response-body break-words whitespace-normal">Content-level access rights give you more granular control than the global settings screen, you can restrict access to specific pages or blocks directly in the content tree rather than applying a blanket rule across everything.</p>
<p class="font-claude-response-body break-words whitespace-normal">A practical example: imagine you have a pricing page that should only be visible to authenticated partners. Rather than locking down your entire content tree, you can grant your API client access to everything by default and then explicitly restrict access on those specific items, or invert it entirely, grant no global access, and only open up the specific content the client needs to see.</p>
<p class="font-claude-response-body break-words whitespace-normal"><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-KagMkB0nHI/84fd374988f4ffa674e61c110c8dd272a70b53a3aaac9b9e69a3c7a2f7904af1773ebb6a4731948214519ccbc5ec37577bafd38a338a450b09e5e0eba3bb6fa71cdd6284c0442e856b1467f4de13af0e9fd093cf7735eb69e73f71e0c32465a8cf3f00c1?fit=max&fm=webp&lossless=true" alt="image.png" /></p>
<p class="font-claude-response-body break-words whitespace-normal"><em>Same request, different response. The restricted client's "Pricing" entry isn't returned as a 403 error, it's simply omitted from the response. This is what makes content-level access rights powerful: the client doesn't need to know what they can't see, and the API does the filtering server-side.</em></p>
<p class="font-claude-response-body break-words whitespace-normal"> </p>
<p class="font-claude-response-body break-words whitespace-normal">The result isn't binary. It's not just 200 or 403, you can build quite precise access models by combining global and content-level rights.</p>
<p class="font-claude-response-body break-words whitespace-normal">Content-level access rights are set directly on a specific page or block in the edit interface. To access them, right-click the item in the content area or page tree and select Edit, then look for the Visible to panel at the top of the properties view. If access is unrestricted it will show as Everyone. Click Manage to open the Access Rights dialog and configure it the same way as the global screen.</p>
<p class="font-claude-response-body break-words whitespace-normal"><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-qR4ivN8SRr/b1a50ba1bf085a982d94ee754c078da101225a16e25244fc5d9c8cbc736292fe097f308e83577c3f01d0fae8184840d72d542e812eb4618722716dc813d7e5abb3de10c714b93db366a20b4bd0b3c5b580d83a9ddbd9f031491b687fa4d36d3d1d50f4ca?fit=max&fm=webp&lossless=true" alt="image.png" /></p>
<p class="font-claude-response-body break-words whitespace-normal"><em>Right-clicking a content item in the page tree to access its properties</em></p>
<p class="font-claude-response-body break-words whitespace-normal"> </p>
<p class="font-claude-response-body break-words whitespace-normal"><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-WSEoq3HxlV/50e6bbbae79aa96c3d964669a0a78de6d46fef1b38a276d48351652090e0cf572a26a24277995b9aac202280dd6e1a98f69eb35f29ab8c264b53d408910f12febb1db17a875ab48629dde4cf5385c47fd04443d133025250ed1f71e4beddb28d649acdcf?fit=max&fm=webp&lossless=true" alt="image.png" /></p>
<p class="font-claude-response-body break-words whitespace-normal"><em>The "Visible to" panel showing the current access restriction status for a content item, with the Manage link to open the Access Rights dialog</em></p>
<p class="font-claude-response-body break-words whitespace-normal"> </p>
<p class="font-claude-response-body break-words whitespace-normal"><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-gRug85CPa2/a655f207b12969e892ee42f18c06fe4559edc2458edd8eac4fdba97ca66f1b57940a77f4656e4e94deb5d320983ab7ce7b56f93992910a7c1f502243c1294c8c8349eb52f165b0cbd6caddda4cbe605aaf827322729400de2e1d68bc28f44516d684351c?fit=max&fm=webp&lossless=true" alt="image.png" /></p>
<p class="font-claude-response-body break-words whitespace-normal"><em>The Access Rights dialog for a specific content item, with alloy-client granted Read access and "Inherit settings from parent item" unchecked to override the global defaults</em></p>
<h4 class="text-text-100 mt-2 -mb-1 text-base font-bold"> </h4>
<h4 class="text-text-100 mt-2 -mb-1 text-base font-bold"><strong>Step 5: Make your first authenticated request</strong></h4>
<p class="font-claude-response-body break-words whitespace-normal">With your token in hand (from Step 3) and access rights set, you can now call the API. Pass the token as a Bearer token in the <strong>Authorization</strong> header.</p>
<div class="relative group/copy bg-bg-000/50 border-0.5 border-border-400 rounded-lg focus:outline-none focus-visible:ring-2 focus-visible:ring-accent-100">
<div class="overflow-x-auto">
<pre class="code-block__code !my-0 !rounded-lg !text-sm !leading-relaxed p-3.5"><code>curl -X GET https://your-site.com/api/episerver/v3.0/content/{contentGuid} \
-H "Authorization: Bearer eyJhbGci..."</code></pre>
</div>
</div>
<p class="font-claude-response-body break-words whitespace-normal"><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-FU_Ev1Aesh/e10d121a20a2164e0dae719606c8455da4b0249791f5133404aa422e9e1305da7a25b2c0c706bad935e45143206bb1573e2b9cc0d2ba6bd276a2b647b477549c2853b76b35191888168aaa288e0c1580f4596e7bf7d5c0283f5f076a95e09b06e0cebea2?fit=max&fm=webp&lossless=true" alt="image.png" /></p>
<p class="font-claude-response-body break-words whitespace-normal"><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-NXSO-5LtU5/e6aa4fcd051b0c43b89b8c85ad1dce2c781e14eb93a6f63afb206b3780777bf8e57bab1dadce5aa8e54b7a205305f2ba10bfb1a792846708e43936e9ae6a37e80ab382f0de3587e031b5aaa2dc4a88bf2655eece10f86e21527fd89bd1e5f87d155ff6b0?fit=max&fm=webp&lossless=true" alt="image.png" /></p>
<p class="font-claude-response-body break-words whitespace-normal"><em>Success response from the Content Delivery API (200 - OK)</em></p>
<p class="font-claude-response-body break-words whitespace-normal"> </p>
<p class="font-claude-response-body break-words whitespace-normal">However, if I revoke read access from the OpenId Application, I get the following:</p>
<p class="font-claude-response-body break-words whitespace-normal"><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-qxuy8jsqAm/3bb819b8f43ca3a5307fb37c86c495da49bb3b98fede2645dcb989df111a4d3581549553ca3323489dbc9c169cdfbba8cfcf395c34c048d66d598408810c86281c422c293e4bed5605e2a0e7099c49380d8c3bbc2d3725707840509617be42aa044340b0?fit=max&fm=webp&lossless=true" alt="image.png" /></p>
<p class="font-claude-response-body break-words whitespace-normal"><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-4bM8czjC1c/1f9f13813cdbbf1744799c9aa89168fde0b36192909142daf589b5707d800ec9b9c91de53a2dfe3bf26c28d318cf550e9cedf3f32a18daea6b22f5dd0f884ca723c2ec77b1a9270724da6dc853706a241ee58975287d316102a1a095bef86ee8849e61bb?fit=max&fm=webp&lossless=true" alt="image.png" /></p>
<p class="font-claude-response-body break-words whitespace-normal"><em>Forbidden response from Content Delivery API (403 - Forbidden)</em></p>
<hr class="border-border-200 border-t-0.5 my-3 mx-1.5" />
<h3 class="text-text-100 mt-3 -mb-1 text-[1.125rem] font-bold"><strong>Common errors and what they actually mean</strong></h3>
<p class="font-claude-response-body break-words whitespace-normal">For the last example, the <strong>403 </strong>is exactly what we'd expect, but it's worth understanding the difference between a <strong>401</strong> and a <strong>403</strong>, since they're easy to confuse and point to very different problems.</p>
<p class="font-claude-response-body break-words whitespace-normal"><strong>401 Unauthorized</strong> means the API doesn't recognise or can't validate the token itself. Either it's malformed, it's expired, or the API isn't configured to accept it. Check that you're passing <strong>OpenIDConnectOptionsDefaults.AuthenticationScheme </strong>into your API registrations in <strong>Startup.cs</strong>, that your token hasn't expired (3599 seconds), and that your <strong>client_id</strong> and <strong>client_secret</strong> match exactly what's registered in CMS Admin.</p>
<p class="font-claude-response-body break-words whitespace-normal"><strong>403 Forbidden</strong> means the token is valid and recognised, but the application it belongs to doesn't have permission to access that content. This is the access rights problem covered in the previous step, the API knows who you are, it just won't let you in.</p>
<p class="font-claude-response-body break-words whitespace-normal"><strong>Token endpoint returns 404.</strong> The OpenID Connect middleware isn't registered, or the package isn't installed. Confirm the NuGet package is installed and correctly configured in <strong>Startup.cs</strong>.</p>
<p class="font-claude-response-body break-words whitespace-normal"><strong>invalid_client error from the token endpoint.</strong> The <strong>client_id</strong> or <strong>client_secret</strong> doesn't match what's registered in CMS Admin (or code). These must be identical, including case.</p>
<p class="font-claude-response-body break-words whitespace-normal"><strong>invalid_scope error from the token endpoint.</strong> The scope you're requesting (<strong>epi_content_management</strong>, etc.) doesn't match what was registered for the client in CMS Admin.</p>
<p class="font-claude-response-body break-words whitespace-normal"><strong>unsupported_grant_type from the token endpoint.</strong> The client was not registered with the <strong>client_credentials</strong> grant type. Check the application configuration in CMS Admin and ensure Client Credentials is selected as a permitted grant type.</p>
<hr class="border-border-200 border-t-0.5 my-3 mx-1.5" />
<h3 class="text-text-100 mt-3 -mb-1 text-[1.125rem] font-bold"><strong>Conclusion</strong></h3>
<p class="font-claude-response-body break-words whitespace-normal">Getting the Optimizely content APIs working for the first time involves piecing together information from several different sources, the official docs, community posts, and a fair amount of trial and error. Hopefully this post brings it all into one place and saves someone the same legwork.</p>
<p class="font-claude-response-body break-words whitespace-normal">If you're already on CMS 13 or considering the move, Optimizely Graph changes the delivery layer significantly and much of the authentication setup described here won't apply in the same way. But for teams on CMS 12 or those still needing to use any of the content APIs, this remains the path.</p>2026-06-22T13:31:38.0000000ZBlog postOptimizely Opal: How to Build Effective Workflow Agents<div><span style="font-size: 14pt;">If you're building workflow agents in Optimizely Opal, this post covers how specialized agents pass context to each other, why keeping agents small and focused matters, and a useful trick for handling situations where you're not sure how to proceed.</span><br /><br /></div>
<div><span style="font-size: 14pt;">I recently decided to put Optimizely Opal through its paces. The experiment: build a simple mock API, feed external data into Opal, and see if a workflow agent could take it from there and autonomously publish content to the CMS, with no human intervention required.</span><br /><br /><span style="font-size: 14pt;">The workflow agent I built pulls data from an external mock API on a schedule, analyzes it, checks it against existing content in the CMS, makes a judgement call on whether a new article is warranted, and if it is, writes and publishes it to the CMS, all without any human intervention.</span><br /><br /></div>
<div><span style="font-size: 14pt;">It is made up of 5 specialized agents, each with a single responsibility, and a condition that branches the workflow based on whether a new article is warranted.</span><br /><br /></div>
<div><span style="font-size: 14pt;">My example consists of the following:</span><br /><br /></div>
<ul>
<li>An agent that retrieves route information from the mock AviationStack API</li>
<li>An agent that compares the route info with articles published in the CMS, and makes a judgement call on whether the info from the API call warrants a new article in the CMS</li>
<li>An agent that writes an article based on the info received from the external mock AviationStack API</li>
<li>An agent that publishes the new article to the CMS</li>
<li>An agent that gracefully ends the workflow if no new article is needed</li>
</ul>
<p><br /><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-etsUzv2Dz7/3408a8416b38371b4a0a1011e247e5b4e5e77bb263977247b0959774ff8866ac828fd6d9e6d45d4a68071da6794cd9b31e81b41c9d373cd0f98c28b0fa85bc306cb1f0ba3f63e13021abea570172c64fdace84bb6a029614852e4ee55aec1581d21f86d7?fit=max&fm=webp&lossless=true" alt="image.png" /><br /><em><br />The full workflow agent. A scheduler triggers the process, data flows through each specialized agent in sequence, and a condition branches the workflow: TRUE continues to writing and publishing, FALSE ends the workflow cleanly</em></p>
<p> <br /><span style="font-size: 14pt;">If you want to build a similar workflow agent yourself and apply some of the tips here in practice, here’s what you need:</span></p>
<ul>
<li style="font-size: 14pt;"><span style="font-size: 14pt;">Optimizely Opal</span></li>
<li style="font-size: 14pt;"><span style="font-size: 14pt;">Access to Optimizely CMS</span></li>
<li style="font-size: 14pt;"><span style="font-size: 14pt;">A mock API with a Custom Tool configured in Opal</span></li>
<li style="font-size: 14pt;"><span style="font-size: 14pt;">Basic familiarity with creating specialized agents in Opal</span></li>
</ul>
<h1 style="text-align: left;"><span style="font-size: 36pt;">Here's what I learned</span><span style="font-size: 36pt; color: rgb(149, 165, 166);"><br /></span></h1>
<hr />
<h1 style="text-align: left;">There’s no prompting between specialized agents</h1>
<div><span style="font-size: 14pt;">Each agent passes its output directly to the next and runs completely on its own, with no human in the loop. This keeps the workflow consistent and predictable, but it also means you need to be deliberate about what each agent outputs, because the next agent depends on it entirely.</span></div>
<div><br /><span style="font-size: 14pt;">Agent 1 output:</span><strong><br /></strong><br /><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-x86SnAX_nl/04321c3dacc79ff08a0e50ab4ef5d1395bce005a2833c489d7a4b07620421b8a25558afd065d4f84eb5a8f142735d8c7a16f055f22ffdbba483ce02c24b572933eea4059a10bcbd7fc2bacf09d32a9b319a21a261d2e93613658e2309e64058eb5ad7f3d?fit=max&fm=webp&lossless=true" alt="image.png" /></div>
<div><em><br />The first specialized agent outputs a simple JSON object containing the route information retrieved from the mock AviationStack API</em></div>
<p><br /><span style="font-size: 14pt;">Agent 2 Input:</span><strong><br /><br /><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-E_3xcxTabY/912d743ab0f4926d01b83641f9962891a9e74717061f1b1627c8f4f13f56130f0d16de0c633d3ad468347b2e40fea7cc98acf787fd96287fe03251229eaec0c03447a6715e5b27610f0a668a3b0460a039269b4d430926f2532d7e4412ac13e3519eb0eb?fit=max&fm=webp&lossless=true" alt="image.png" /><br /></strong><br /><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-QB8U70NVT3/7b84ae2291e4ee54ee6e79af84649770c8f4e0ad6abf05b347e3298ddf6f1c04513c49a97a83df7bf2fd0511b0752f875c57abdafbc7c009a2d1f7342a09b7e88afe36eac29b803c33d28cf09c3b1f31fa9c0de26b2024b9a27bcf879ca1971af303a6cb?fit=max&fm=webp&lossless=true" alt="image.png" /></p>
<div><em>That same "routes" object becomes the input for the next agent, defined as a required variable and referenced directly in the prompt template. This is what "output becomes input" looks like in practice.</em></div>
<hr />
<h1>Create as many specialized agents as you need</h1>
<div><span style="font-size: 14pt;">Don't hesitate to create as many agents as your workflow needs, and be as granular as necessary. Each agent should do one thing well, not many things adequately.</span><br /><br />
<div><span style="font-size: 14pt;">Developers will recognize this as the Single Responsibility Principle (SRP), and it applies just as well here. For those less familiar with the term, the idea is simple: don't create one agent that retrieves external data, analyzes it, writes an article, and publishes it. That's too much for one agent to handle reliably, and you'll end up with bloated instructions. Split those responsibilities across separate agents instead, and let them pass context to each other.</span></div>
<br /><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-sMM-Tmyes9/61ea231a49ab6ce082d59c3280cebe49ccf630168f5711d6ac95fd1bf44ae642972dce83161d529b5fba3bffcc92e05f253c88f6455a1b8956db6c2f0a7e6515195ad3317906a8ac44f162bd09dad40ac87b8d156b245522a56d496a965b52e663bfb3e9?fit=max&fm=webp&lossless=true" alt="image.png" /><br /><br /></div>
<div>
<div><em>A single agent handling too many responsibilities. This is harder to debug, harder to maintain, and more likely to produce inconsistent results.</em></div>
</div>
<h1><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-gjt814Dg6l/3b1f8e8e38428374d003026b0770899e52979739d84faf1f7befc8627b0c86aafee258fd6aa56c0aed5fd7fb1e290551d996993d788d68c2960f742fce7bc24298bbda5ddd838b27ca48309889ac291c38cf1085afa53fd8139594e9415051527e0eadfa?fit=max&fm=webp&lossless=true" alt="image.png" /></h1>
<div><em>The same workflow split across three focused agents, each with a single responsibility, and each passing its output to the next.</em></div>
<hr />
<h1>If you run into a gray area and you're not sure how to handle it, create a specialized agent</h1>
<div><span style="font-size: 14pt;">This is simpler than it sounds. When you hit a question like "How do I get it to write an article?", you create a specialized agent for it. "How do I get it to publish to the CMS?", you also create a specialized agent for it. Most problems in a workflow agent have the same answer: a focused, purpose-built specialized agent.</span><br /><br /></div>
<div><span style="font-size: 14pt;">A good example from my own workflow: when the condition evaluates to false, meaning the external data doesn't warrant a new article, I needed the workflow to simply stop cleanly. There's no built-in "do nothing" option, but the answer was straightforward: create an "End Workflow" agent whose only job is to acknowledge the decision and exit gracefully.</span><br /><br /><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-2tv3E7USqI/7715b92663891aeb140f10a67422095138d453cdaa125065284a4f1ba266274aa0a691cb8a78ffa01e8fa74f202faea083499b389d56a38ad325e7d628c2d3fc61dcd1254f253d452d8fb0f0d48db3d644f2eadc9b3eff5646f43bf733d3203320c4ecbe?fit=max&fm=webp&lossless=true" alt="image.png" /></div>
<div><em><br />The "End Workflow" agent keeps it simple by design. No tools, no content creation, no external calls. Its only job is to end the workflow cleanly when no action is needed, which is exactly the kind of focused single-responsibility agent your workflow will thank you for later.</em></div>
<hr />
<h1>Don't assume an agent has context from earlier in the workflow unless you explicitly pass it</h1>
<div><span style="font-size: 14pt;">This is an important one. Just because multiple specialized agents live inside the same workflow agent doesn't mean they automatically share context. If Agent 4 needs data that Agent 1 retrieved, you need to explicitly pass it through each agent's inputs and outputs along the way, it won't be there by default.</span><br /><br /></div>
<div><span style="font-size: 14pt;">In my workflow, by the time the article-writing agent needs to do its job, it has no automatic awareness of the route data retrieved at the start. If I want it to have that context, I need to explicitly include it in the outputs of the agents before it, and specify it as an input to the agents that follow.</span></div>
<h1><img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-arF8aKa8Nu/28333b43056d181ee30677a8a0c36cbc391b8cdd2353caa86ebbcdc85376aab333272045c1b19ab42d79436a11f4d4b7e0a2daf625a1b2fd25f3c49b22df4af72eee1c908366c15327e2f333003cd3800e1aabad69f9f8dbc01cb8fa3eb4c1ab1722a169?fit=max&fm=webp&lossless=true" alt="image.png" /></h1>
<div><em>The output schema of my "Gap Analyzer" agent explicitly carries the "routes" object forward, alongside its own "reason" and "publishDecision" fields. Without "routes" being defined here as an output, the article-writing agent downstream would have no access to the original API data, even though it was retrieved earlier in the same workflow.<br /></em><hr /><span style="font-size: 14pt;">That's about it for now! Hope this helps someone else out. If you've built something similar or have any questions or suggestions, I'd love to hear about it in the comments. Thanks for reading!</span></div>
<h1><br /><br /></h1>2026-05-20T09:04:10.0000000ZBlog post