Authentication and authorization
This article covers how to configure OAuth clients, obtain access tokens, and manage signing credentials for production and local development environments for Content Management System (CMS 13).
For an overview of the REST API and its endpoints, see Introduction to the CMS REST APIIntroduction to the CMS REST API.
Configure OAuth clients
OAuth clients authenticate external applications and services that interact with the REST API. Each client requires a ClientId and ClientSecret pair.
Opti ID handles interactive user authentication for the CMS editorial interface. OAuth clients configured through CmsServiceOauthOptions authenticate service-to-service API calls.
Configure clients in appsettings.json
Define OAuth clients in appsettings.json under the Optimizely:Cms:Service:Oauth:Clients section.
{
"Optimizely": {
"Cms": {
"Service": {
"Oauth": {
"Clients": [
{
"ClientId": "YOUR_CLIENT_ID",
"ClientSecret": "YOUR_CLIENT_SECRET"
}
]
}
}
}
}
}Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with values appropriate for your application.
To verify the client configuration, request a token as described in the following sections. A 401 response indicates the client credentials do not match the configured values.
Configure clients with environment variables on DXP
On Optimizely Digital Experience Platform (DXP), configure clients securely using environment variables through the DXP App Settings. Use the standard double-underscore separator convention to map to the JSON hierarchy.
The following example shows the environment variable pattern for the first client (index 0):
Optimizely__Cms__Service__Oauth__Clients__0__ClientId=YOUR_CLIENT_ID
Optimizely__Cms__Service__Oauth__Clients__0__ClientSecret=YOUR_CLIENT_SECRETAdd additional clients by incrementing the index (for example, __1__ClientId, __1__ClientSecret).
Configure clients in code for local development
For local testing, configure clients programmatically in Startup.cs:
if (_webHostingEnvironment.IsDevelopment())
{
services.Configure<CmsServiceOauthOptions>(o =>
{
o.AddDevelopmentSigningCredentials();
o.Clients.Add(new OauthClient
{
ClientId = "localtest",
ClientSecret = "localtest"
});
});
}Configure signing credentials
Signing credentials secure tokens that the OAuth endpoint issues. The configuration differs between DXP-hosted environments and local development.
DXP environments
On DXP, services.AddCmsCloudPlatformSupport() configures signing credentials through a secure certificate. This method is required for DXP deployment and handles certificate management without manual configuration. See Deploy an existing CMS site.
Local development
For local development, call AddDevelopmentSigningCredentials() on CmsServiceOauthOptions. This method generates in-memory signing credentials on each application startup. Signing credentials
if (_webHostingEnvironment.IsDevelopment())
{
services.Configure<CmsServiceOauthOptions>(o =>
o.AddDevelopmentSigningCredentials());
}Request an access token
The OAuth token endpoint supports the client_credentials grant type and issues short-lived tokens. To request a token, send a POST request to the token endpoint with your client credentials.
Token request
JSON request body
POST /_cms/v1/oauth/token
Content-Type: application/json
{
"grant_type": "client_credentials",
"client_id": "CLIENT_ID",
"client_secret": "CLIENT_SECRET"
}URL-encoded request body
POST /_cms/v1/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Base64(GetBytes(client_id:client_secret))
grant_type=client_credentialsToken response
A successful request returns a JSON response containing the access token.
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 300
}The expires_in value indicates the token lifetime in seconds. Request a new token before the current token expires.
Authenticate API requests
Include the access token in the Authorization header of each API request.
GET /_cms/v1/contenttypes
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...Troubleshoot
401 Unauthorized response
Verify that the ClientId and ClientSecret match the values configured in appsettings.json or environment variables. Verify the token has not expired.
Token endpoint returns 404
Confirm that the application calls AddCms() in the service configuration. This method registers the REST API v1 and OAuth endpoints.
Signing credential errors in local development
Ensure AddDevelopmentSigningCredentials() is called in the development configuration block. This method must execute before the application attempts to issue tokens.
Environment variable configuration not applying on DXP
Verify the double-underscore separator pattern. For example, use Optimizely__Cms__Service__Oauth__Clients__0__ClientId rather than colons or single underscores.