Loading...
Area: Episerver Content Management API
Applies to versions: 2 and higher

Configuration

Recommended reading 

The Episerver Content Management API (CMA) has the ContentManagementApiOptions (located in the EPiServer.ContentManagementApi namespace) where you can configure the API. Currently, there are security-related and support flatten property model settings that you might want to change.

In this topic

Security

CMA has three authorization levels:

  • Allow Scopes. Scopes that require to hit any method of CMA endpoints. The user needs to have at least one of configured allowed scopes in order to call the API endpoints.
  • Required Role. The required role must be assigned to content in order to be accessible in the Content Management API.
  • Privilege. The user must have privilege(s) on content in order to perform an action.

As stated in Getting started, our OAuth package does not support scope by default, so that this setting should be disabled in case the application use the package (see sample below). In case clients use another authorization server that supports scope, the default scope value epi_content_management can be configured at initialization time (see sample below). For required role, the default value is ContentApiWrite and it also can be configured at initialization time.

[InitializableModule]
public class DependencyResolverInitialization : IConfigurableModule
{
    public void ConfigureContainer(ServiceConfigurationContext context)
    {
        context.ConfigurationComplete += (o, e) =>
        {
            // Example how to allow anonymous calls
            context.Services.Configure<ContentManagementApiOptions>(c =>
            {
                // Our default OAuth package does not support scope for now so that it should be disabled if you use our OAuth
                c.SetDisableScopeValidation(true);

                // this can be any values
                c.SetRequiredRole(string.Empty);

                // just in case you use another authorization server that supports scope
                // c.AddAllowedScope("your_scope_name");
            });
        };
    }

    public void Initialize(InitializationEngine context) { }
    public void Uninitialize(InitializationEngine context) { }
    public void Preload(string[] parameters) { }
}

Flatten

As stated in Getting started, flatten configuration controls data format used in serialization (for GetCommonDraft endpoint) and deserialization (for data sent to other endpoints). Its value can be configured at initialization time.

Example:
When we use any endpoints (Get common draft, post, put, patch …) in CMA without flatten, the data format is:

{
  "name": "Alloy Plan",
  "metaTitle": {
    "value": "Alloy Plan, online project management",
    "propertyDataType": "PropertyLongString"
  },
  "metaDescription": {
    "value": "Project management...",
    "propertyDataType": "PropertyLongString"
  },
  ...
}

With flatten, the data format is:

{ 
  "name": "Alloy Plan", 
  "metaTitle": "Alloy Plan, online project management", 
  "metaDescription": "Project management...", 
  ...
} 

Configure flatten setting like this:

[InitializableModule] 
public class DependencyResolverInitialization : IConfigurableModule
{
    public void ConfigureContainer(ServiceConfigurationContext context)
    {
        context.ConfigurationComplete += (o, e) =>
        {
            // Example how to support flatten
            context.Services.Configure<ContentManagementApiOptions>(c =>
            {
                c.SetFlattenPropertyModel(true); 
            });
        };
    }

    public void Initialize(InitializationEngine context) { }
    public void Uninitialize(InitializationEngine context) { }
    public void Preload(string[] parameters) { }
}
Do you find this information helpful? Please log in to provide feedback.

Last updated: Apr 20, 2021

Recommended reading