Introduction to the CMS REST API
The CMS REST API is included in every CMS 13 project. The AddCms() method registers both the REST API v1 endpoints and the OAuth token endpoint, so no additional packages or registration calls are required to enable the API.
The CMS REST API is not intended for delivery. Optimizely recommends using Optimizely Graph for content delivery.
API endpoint paths
CMS 13 exposes the REST API at the following base paths:
- /_cms/v1 – The CMS REST API v1 root. Content, content type, and management endpoints are available under this path.
- /_cms/v1/oauth/token – The OAuth token endpoint for requesting access tokens.
The AddCms() method in your application startup calls .AddOptimizelyCmsServiceV1().AddOauthEndpoints(), which registers these endpoints. No additional service registration is needed.
REST API configuration differences from CMS 12 and CMS 13
CMS 13 simplifies REST API configuration compared to CMS 12 with Content Management and Content Definitions API. It does not replace the Content Delivery API.
While it is essentially the same API as CMS 13 exposes, there are some differences between the two. The following table summarizes the differences.
Area | CMS 12 | CMS 13 |
|---|---|---|
API registration | Install EPiServer.ContentManagementApi and EPiServer.ContentDefinitionsApi NuGet packages and call AddContentManagementApi() and AddContentDefinitionsApi() in Startup.cs | Automatic with AddCms(), available at /_cms/v1 |
Authentication library | Install EPiServer.OpenIDConnect NuGet package and configure OpenIddict with ASP.NET Identity | Built-in OAuth at /_cms/v1/oauth/token, configured through CmsServiceOauthOptions |
Client configuration | Define OpenIDConnectApplication objects in code with scopes and redirect URIs | Define clients in appsettings.json or environment variables with ClientId and ClientSecret |
Signing credentials | Provide X509Certificate2 manually or use useDevelopmentCertificate: true, DXP auto-provides through CloudPlatform.Cms 1.6.1 or later | DXP auto-provides through AddCmsCloudPlatformSupport(), local dev uses AddDevelopmentSigningCredentials() |
Grant types supported | Authorization code, client credentials, resource owner password | Client credentials |
Scope validation | Optional through DisableScopeValidation | Managed through client configuration |
Migrate from CMS 12 authentication
If you are upgrading from CMS 12 to CMS 13, replace the EPiServer.OpenIDConnect package configuration with the CmsServiceOauthOptions approach described in Authentication and authorizationAuthentication and authorization. CMS 13 does not require the AddOpenIDConnect<ApplicationUser>(), AddContentManagementApi(), or AddContentDefinitionsApi() calls. Instead, CMS 13 handles API registration and OAuth endpoint setup through AddCms().
For CMS 12, the token endpoint was at /api/episerver/connect/token. In CMS 13, the token endpoint is at /_cms/v1/oauth/token.