Blog posts by Jon Williams

Optimizely Graph Best Practices - Security, Access Control and Performance Optimisation

Thu, 29 Jan 2026 21:49:41 GMT

Introduction

Building on Part 1's content modeling and querying practices, this Part 2 focuses on the security and performance considerations essential for running Optimizely Graph in production environments.

We'll explore authentication strategies - from Single Key for public content to HMAC with role-based access control for restricted scenarios - and discuss when a Backend for Frontend (BFF) layer provides crucial security benefits. You'll also learn performance optimisation techniques including cached templates, query fragments, and approaches to eliminate inefficient query patterns.

These operational practices ensure your Graph implementation delivers content securely and efficiently at scale. In the final post of this series, we'll cover API key management, integration strategies, and governance approaches for long-term maintainability.

1. Security & Access Control

Do:

1. Use role-based API keys

If your content is publicly available then you can use the 'Single key' mechanism for authenticating and reading content from Graph.

This key can be accessed from the PaaS Portal:

Note that 'Single key' access only returns content that is accessible to the the Everyone group within the Content Management System. It is good for general website content, as it is read-only, fast and can be called directly from a frontend (headless) application.

2. Respect CMS content permissions

If you need to access restricted content (i.e. content that is not accessible by the Everyone group) then you'll need to do this using 'role-based access control' (RBAC) and preferably through HMAC.

HMAC access uses the 'App key' and 'Secret' (available from the PaaS Portal) and can be combined with `cg-username` and `cg-roles` request headers to only fetch content where one of the roles or the username specified has read access.

However, given that this mechanism requires the 'App key' and 'Secret', which could be used to provide full access to all Graph resources without restriction, it important that these are not used from frontend code. If these are needed then a Backend for Frontend (BFF) layer is recommended to securely proxy requests to Graph while keeping credentials server-side.

3. Avoid exposing draft or non-public content

Using the 'Single key' authentication mechanism only gives access to published, non-expired content that is available to everyone.

However, if using the 'App key' and 'Secret' to authenticate then it is possible to include additional headers (`cg-include-deleted`, `cg-include-hard-deleted` and `cg-include-expired`) to also include deleted and expired content. If you are using these (or user / role based access) for any reason then proceed with care, as there may be out-of-date or potentially sensitive content being exposed.

4. Be aware that GraphiQL is openly available

Be aware that anyone with your Single key can access the GraphiQL interface at https://cg.optimizely.com/app/graphiql?auth={singlekey}, which exposes your full content schema through introspection.

If you choose to expose the Single key in client-side code (as is common for a headless website) then at least be aware that this is a possibility and potentially increases the attack vector on your estate.

If you elect to implement a BFF then this can be used to proxy requests to Optimizely Graph, allowing the Single key to be hidden, as well as adding functionality like caching, rate limiting, transformation and more sophisticated authentication.

2. Performance Optimisation

Do:

1. Use cached templates and cached queries

This is one of the biggest performance gains to be made when querying Optimizely Graph!

Rather than 'hardcoding' queries, such as this:

query GetArticlesByCategory {
  ArticlePage(
    where: { TeaserText: { contains: "Technology" } }
    limit: 10
    locale: "en"
  ) {
    items {
      Name
      TeaserText
      RelativePath
    }
  }
}

... Using a query containing GraphQL variables, such as the following, enables Optimizely Graph's cached template feature:

query GetArticlesByCategory {
  ArticlePage(
    where: { TeaserText: { contains: "Technology" } }
    limit: 10
    locale: "en"
  ) {
    items {
      Name
      TeaserText
      RelativePath
    }
  }
}


Including the query `parameter stored=true` and the header `cg-stored-query: template`, along with this restructuring allows the translated query structure to be cached and only variable values are substituted, dramatically improving performance.

More details on this can be found in Jonas Bergqvist's blog post listed in the Related Links below.

2. Cache responses at edge or client

Another advantage of using a BFF middleware would be to facilitate the caching of content coming from the Optimizely Graph API.

In this situation, if the content rarely changes then this could be cached within the BFF application or by providing a more fine-grained caching strategy for clients of the BFF (or CDN).

3. Use query fragments for reusable content blocks

Define GraphQL fragments to standardise and optimise how frequently used structures (e.g. banners, nav items) are retrieved.

For example, rather than repeating the sections for `` and ``, the following query has been implemented using fragments:

# Common image fragment
fragment ImageFields on ContentReference {
  Url
  AltText
  Width
  Height
}

# Common link fragment  
fragment LinkFields on ContentReference {
  Url
  Text
  Title
  Target
}

# Common page metadata fragment
fragment PageMetadata on IContent {
  Name
  RelativePath
  _metadata {
    published
    lastModified
    locale
  }
}

# Full query using all fragments
query GetProductPage($id: String!) {
  ProductPage(where: { _metadata: { key: { eq: $id } } }) {
    items {
      ...PageMetadata
      
      ProductName
      ProductDescription
      
      ProductImage {
        ...ImageFields
      }
      
      RelatedProducts {
        ...on ProductPage {
          ProductName
          ThumbnailImage {
            ...ImageFields
          }
          ProductLink {
            ...LinkFields
          }
        }
      }
      
      CallToAction {
        ...LinkFields
      }
    }
  }
}

Whilst there will be a small performance gain from the (slightly) shorter query content, this has the added benefits of:

DRY Principle: Define field selections once, reuse everywhere
Consistency: All queries return the same fields for the same content types
Maintainability: Update fields in one place, all queries automatically updated
Readability: Smaller queries are easier to read, understand and debug
Optimisation: Graph can better optimise repeated fragment usage

4. Avoid N+1 issues in nested queries

The N+1 problem occurs when you fetch a list of content items, then make separate queries to retrieve related content for each item (e.g., fetching 10 events pages, then making 10 additional queries to get each event's location). This results in poor performance.

Solution: Use GraphQL's nested query capabilities to fetch related content in a single request. Here is an example of this from the scenario above:

query GetEventsWithLocations {
  EventPage(limit: 10) {
    items {
      Name
      EventDate
      Description
      LocationReference {
        ...on LocationPage {  # Expand the reference inline
          Name
          Address
          City
          PostalCode
          Country
          Latitude
          Longitude
        }
      }
    }
  }
}

When querying content with ContentReference or ContentArea fields, expand those references inline using fragments rather than fetching them separately.

If multiple queries are unavoidable, implement caching to prevent redundant requests for the same content, or use bulk queries with the in operator to fetch multiple related items at once.

Don’t:

1. Use Graph for high-frequency real-time queries (e.g. stock price tickers, rapidly changing datasets)

Optimizely Graph is optimised for content delivery, not real-time data streams. Whilst it can be used to serve data from external (non-Optimizely) systems, it excels with content that changes at human editorial pace (pages, blog articles, products, etc.) rather than data that updates multiple times per second.

If your application requires high-frequency updates like stock price tickers, live sports scores, real-time chat messages, IoT sensor readings, or rapidly changing inventory levels, these should be served from a dedicated real-time backend (Redis, WebSockets, SignalR) or a specialised time-series database. Use Graph for what it excels at - flexible querying and delivery of editorial content.

Summary

Running Optimizely Graph securely and efficiently in production requires balancing accessibility with control. Use Single Key authentication for public content, implement HMAC with role-based access for restricted content, and consider a Backend for Frontend (BFF) layer when exposing credentials would create security risks. Maximise performance through cached templates, query fragments, and nested queries that eliminate redundant requests.

Combined with Part 1's content modeling and querying best practices, these operational guidelines ensure your Graph implementation remains secure, performant, and maintainable as your content delivery needs evolve and scale. In the final post of this series I'll be giving our best practices for managing and maintaining the implementation, including: managing API keys, integration strategies and governance.

Optimizely Graph Best Practices - Content Modelling and Querying

Fri, 16 Jan 2026 06:43:03 GMT

Introduction

With the Mando Group team having worked extensively with Optimizely Graph over the last 12+ months, we have uncovered a number of best practices along the way.

For readability, I have split the best practices across three posts. This post includes sections on content modelling and querying content within Optimizely Graph. Part 2 will contain our best practice findings relating to security & access control and performance optimisation and then the third on managing and maintaining the implementation, including: managing API keys, integration strategies and governance.

These posts are designed for developers, solution architects, DevOps teams, and anyone responsible for building Optimizely Graph-powered applications or sites.

As with a lot of best practice guides, this post leans heavily on the existing contributions of others from within the Optimizely Community and I've given a list of related links at the bottom of the post for those that have most significantly contributed.

1. Content Modelling Best Practices

Good content modelling is essential to getting value from Graph. However, most of the items in this area are just normal content modelling best practices, rather than anything Optimizely Graph-specific. These include:

Do:

1. Do: Design with reuse in mind

Use modular content types (e.g. Author, PromoBlock, CTA, FAQ) that can be linked and reused in multiple places.

Doing this allows content to be shared in multiple places – providing familiarity and reducing the content maintenance burden for editors.

Additionally, it provides a consistent structure for Optimizely Graph content consumers (e.g. headless websites, mobile applications, etc.) and facilitates more sophisticated caching strategies.

2. Do: Use structured fields

Favour structured fields (int, bool, DateTime, ContentReference, etc.) over (plain or rich) text fields where appropriate. This allows cleaner queries against these fields and more reliable filtering.

3. Do: Establish meaningful relationships

Use ContentArea, ContentReference, and ContentReferenceList fields to link content objects logically (e.g. a BlogPost with related Author, Tags, Category, or PromoBlock).

Whilst having more generic content types (e.g. 'RichTextField') may reduce the overall number of content types, it makes understanding and working with the content less intuitive.

4. Do: Use naming conventions consistently

Standardise field names to simplify query building and team handovers.

For example, don't call the main H1 field 'Title' in one content type and then 'Heading' in another defined content type.

5. Do: Set PropertyIndexMode correctly

As stated in the online documentation (here), if you know for sure that a particular field within a page or block will not be used for filtering or searching on then you can set the `OutputOnly` mode using the following syntax:

[GraphProperty(PropertyIndexingMode.OutputOnly)]
public virtual string Description { get; set; }

Additionally, if you want the field to be searchable (using a where clause) but it does not need to be searchable with full-text search then you can set this as follows:

[GraphProperty(PropertyIndexingMode.Default)]
public virtual string Description { get; set; }

Just be mindful that if the Graph client requirements change around these fields then you'll need to make the necessary attribute change/removal, re-deploy the application and re-index the Graph content.

Don't:

1. Don't: Use website-specific field names

Keep in mind that content stored in Graph may be used in lots of different contexts (e.g. Website, mobile app, kiosk application, etc.) and avoid using field names that only make sense in one of these.

For example, don't call a field `RightColumnText` if the content could also be used on a mobile app where the content is shown in a single column. Instead, name the field something like `SecondaryContentText` - which makes sense in both contexts.

2. Don't: Overuse XhtmlString (a.k.a. Rich text) fields

Breaking larger blocks of rich text into more structured, separate fields may make the content more flexible and reuse simpler.

For example, rather than having a rich text field that contains some formatted text, an image and a table, split this content into separate fields to allow each part to be used independently (without the need for additional client-side processing).

3. Don't: Duplicate similar content types across sites or channels

Having consistent content types across as much of the client's digital estate as possible makes reuse simpler. For example, don't have a 'Blog Article' content type on their main site and then a different 'Blog Post' content type on one of their microsites – Having shared content model projects allows reuse of content types as much as possible.

2. Querying Best Practices

Do:

1. Do: Use specific, shallow queries

Avoid querying deeply nested objects unless required. Shallow, purpose-specific queries are faster and more maintainable.

Request only the fields that you will use on your frontend. There can sometimes be a temptation to fetch additional fields for testing or verification purposes. Ensure that you remove these from your final queries.

2. Do: Paginate large result sets

Optimizely Graph has two mechanisms for paginating large data sets: Cursor-Based vs Offset Pagination.

In line with the Optimizely documentation (here), using the traditional offset pagination (using the standard 'skip' and 'limit' parameters) is typically more efficient on smaller data sets (e.g. fewer than 10,000 results), but the selected mechanism should depend on your individual use case.

Whichever approach, the principle still applies that selecting only the number of results needed, and not needing to discard results, is far more efficient.

3. Do: Use variables for flexibility

Define filters and projections as GraphQL variables to avoid hardcoding and to support front-end reuse.

Always use GraphQL variables instead of hardcoding values directly into your queries.

# Instead of hardcoding values:

query { BlogPost(where: { Status: { eq: "Published" } }, limit: 50) { ... } }

# Use variables:

query GetBlogPosts($status: String!, $limit: Int!) {

BlogPost(where: { Status: { eq: $status } }, limit: $limit) { ... }

}

Doing it this way allows for using cached templates and queries (which I will cover in the second post) – providing significant efficiency gains. However, beyond performance, variables also enable query reusability across components, provide type safety and validation, prevent injection attacks, and make queries easier to maintain.

Ensure that you define explicit types for all variables and use non-null types (!) when values are required. This is particularly valuable in component-based frameworks where the same query can be shared across multiple components with different parameter values.

4. Do: Filter and sort server-side (i.e. Within the Graph query)

A broad rule of thumb should be to apply where and order conditions within Graph queries rather than handling data manipulation in the client-side.

The where clause allows you to filter content based on property values, reducing the amount of data transferred and improving response times. However, not all filtering approaches are created equal.

Use exact matches and equality operators (eq, in) whenever possible, as these execute faster than partial matches or complex string operations. For example, filtering by content type, status, or ID is highly efficient, while using contains or startsWith on large text fields requires more processing.

5. Do: Experiment and consider alternative options

Despite the broad-brush best practice guidelines above, I would still recommend testing your queries and considering all approaches.

For example, if you know that your website visitors almost always scroll to view more articles that are dynamically loaded, then pre-fetching these with a slightly less efficient Graph query (with a bigger page size) and hiding/caching the extra values may provide a faster and more enjoyable user experience.

Don't:

1. Query entire collections with no limits

Avoid querying large collections without specifying pagination parameters. Queries like BlogPost { items { ... } } without a first or limit parameter will attempt to retrieve all matching content, which can cause serious performance issues, timeouts, and excessive memory consumption (on both the server and client).

Optimizely Graph enforces limits, but relying on default behaviours is risky. In production environments with thousands of content items, an unlimited query can easily timeout or overwhelm your application's memory, particularly on mobile devices or lower-powered clients.

2. Request unnecessary fields "just in case" — this increases payload and processing time

Avoid the temptation to request fields that you don't immediately need in your frontend. Queries that fetch every available field—or include extra fields for testing, debugging, or potential future use—significantly increase payload size, processing time, and network transfer costs.

GraphQL's primary advantage is its ability to request exactly the data you need, nothing more. When you query for 20 fields but only render 5, you're wasting resources on both the server (which must retrieve and serialize the extra data) and the client (which must parse and store it). This is particularly problematic on mobile devices or slower connections where bandwidth and processing power are limited.

It's common during development to fetch additional fields for verification or debugging purposes. However, these extra fields often remain in production queries long after they're no longer needed, quietly degrading performance.

Regularly audit your queries as part of code reviews or performance optimization sessions. Lean queries result in faster response times, reduced bandwidth usage, and better overall application performance.

Summary

Effective use of Optimizely Graph starts with thoughtful content modelling and efficient querying practices. By designing reusable, well-structured content types with consistent naming conventions and appropriate indexing modes, you create a foundation that scales across multiple channels and applications. Similarly, crafting specific, shallow queries with proper pagination and server-side filtering ensures optimal performance and maintainability.

The practices outlined in this post - from avoiding deeply nested queries to leveraging GraphQL variables for flexibility - will help you build faster, more reliable Optimizely Graph implementations. Remember that while these guidelines provide a strong framework, every project has unique requirements, so testing and measuring performance in your specific context remains essential.

In the subsequent posts, we'll dive into the operational aspects of running Optimizely Graph in Production, including performance optimisation techniques, security considerations, API key management strategies, integration patterns, and governance approaches. These additional practices will help ensure your Graph implementation remains secure, performant, and maintainable over time.

Stay tuned for Part 2, which will be published in the coming weeks.

Opti ID: What is it and why now is a good time to use it

Wed, 12 Nov 2025 14:38:37 GMT

If you’ve been hearing the term Opti ID floating around and wondering what the fuss is about, let’s break it down in plain English.

What is Opti ID at a high level?

Think of Opti ID as your one key to the Optimizely kingdom. Instead of juggling multiple logins for CMS, CMP, DXP, and other Optimizely tools, Opti ID gives you a single, secure identity across the board. It’s like having one passport for all the countries in the Optimizely world.

What advantages does it bring?

One login, less hassle – No more remembering five different passwords.
Better security – MFA support and modern protocols keep things locked down.
Smooth onboarding – SCIM integration means user and group management is automated.
Future-proof – Opti ID is becoming the standard for all Optimizely services.

Unbranded Opti ID login screen

What will happen if you don’t have Opti ID?

If you regularly work in the Optimizely ecosystem then you’ll start hitting roadblocks.

Some new services (like Optimizely's Opal AI functionality) will require Opti ID from the outset and other existing systems, such as the login to Optimizely World, are moving over to it. Without and Opti ID login, you’ll be stuck with fragmented access to Optimzely systems and manual user management. Basically, life gets harder.

What does this mean in the real world?

Picture this:

You’re an editor working on CMS content, then need to jump into CMP for campaign planning or to upload a DAM asset. With Opti ID, you log in once and move seamlessly between these tools. Without it, you'll need to remember and input two separate passwords (and possibly usernames) for each of the systems - causing a break in your flow and frustration.
Need to manage permissions for your team? Instead of fiddling with settings in multiple separate systems (CMS, CMP, ODP, etc.), you can do it centrally via Opti ID - being able to see exactly which systems a user has access to and which groups they are a member of in one place.
Concerned about a bad guy guessing a password, logging into your CMS and inflicting significant reputational damage (and potentially locking everyone else out of the CMS)? You might want to implement multi-factor authentication (MFA) sooner rather than later. Luckily, that's baked into Opti ID too.

Multi-factor authentication setting enabled within the Admin Centre

I'm interested. What do I need to consider?

There are a few things to consider before deciding whether to move over to using Opti ID. Some questions you will want to think about include:

Do you need access to Optimizely systems such as Helpdesk support, Optimizely World, Optimizely Academy, etc? (Hint: If the answer to this is 'yes' then you will almost certainly need an Opti ID account.)
Are you using more than one product from the Optimizely platform (e.g. CMS, CMP, ODP, etc.)?
Are you using only Optimizely SaaS products (e.g. ODP, Web Experimentation, etc.) or do we need some small additional configuration and code changes to make this work (e.g. on PaaS CMS)?
Do you need the additional security of multi-factor authentication (MFA) on our site or is a simple username and password still sufficient?
Are you happy having a separate username and password (and optionally MFA) for Opti ID or do we want to tie this into our existing authentication system (e.g. Microsoft Entra ID, Okta, etc.)?
Do you want to automatically sync users and groups from our existing authentication system into Opti ID or are we happy to manually create/duplicate these?
How will you we manage the roll out and communication around this change?
How will you test this to ensure that all login flows work (for all user types on all systems) before turning off the old authentication mechanisms?

I already log in to my laptop. Why can’t It just use that authentication?

Good question! It actually can. If your organisation uses Entra ID (formerly Azure AD) or another OIDC-compliant provider such as Okta or PingOne, you can configure Opti ID to trust that identity (rather than having a separate Opti ID username and password). So yes, your laptop login can carry over – you just need to set up the connection within the Optimizely Admin Centre.

Side note: Opti ID also supports SAML based authorisation to allow connectivity to legacy identity providers or those with OIDC restrictions.

How do I manage groups and permissions?

Users and groups can be easily created and centrally managed within the Optimizely Admin Centre. However, many organisations don't want to duplicate these (in Opti ID) and instead just want control them within their existing identity provider (e.g. Entra ID or Okta). To facilitate this, Opti ID supports SCIM provisioning, which means you can sync users and groups from your existing identity provider into the Opti ID platform. No need to duplicate this group membership configuration in two places or to manually add (potentially) hundreds of users within the Opti ID system!

Admin Centre - User management screen

I’ve not had to use this before. Why should I set up Opti ID now?

As mentioned above, new services like Opal already require it and many others, such as access to Optimizely World, Optimizely Academy and Support, are following suit. Setting it up now saves headaches later and gives you a single user account to access to the necessary systems.

Final thoughts

Opti ID isn’t just another login system – it’s the backbone of how Optimizely is moving forward. Get ahead of the curve, make life easier for your team, and lock down security while you’re at it.

If you need help understanding Opti ID, its benefits or technicalities further then please get in touch.