Area: Episerver Service API
Applies to versions: 5 and higher
Other versions:

Installation and configuration - Service API

This section describes how to install and configure EPiServer.ServiceApi as the integration service with OWIN-based authentication and ASP.NET Identity.

Installing NuGet packages

Install Episerver updates through the NuGet Package Manager in Visual Studio. See Installing Episerver updates.

Installing the Service API components

To set up the service layer and related components:

  1. Set the target framework for your project to .NET Framework 4.6.1 or higher by right-clicking on the project and choosing Properties.
  2. Select Tools > NuGet Package Manager > Manage NuGet packages for Solution... (or right-click on the solution References and select there).
  3. Click Settings to create a source pointing to the Episerver NuGet feed.
  4. Open the Online section and select the source you just created.
  5. Install EPiServer.ServiceApi or EPiServer.ServiceApi.Commerce if working with Commerce, and all dependencies (including both Episerver and third party packages) Episerver-based solution (either the Commerce sample website or your actual solution).

    Note: Do not install EPiServer.ServiceApi or EPiServer.ServiceApi.Commerce on your Commerce Manager site.

  6. Select Tools > NuGet Package Manager > Package Manage Console, and run the command update-epidatabase.
  7. Running update-epidatabase or Automatic schema updates set administrator permissions automatically, but you should check that they are set correctly. Otherwise, set account permissions for administrators to execute the Service API in the database (tblUserPermission). (If not, an HTTP 401 status is returned.)
  8. Open EPiServerFramework.config and make sure that <appData> has a <basePath> directory that points to a valid location for which IIS has write permissions.
     in your site, the EPiServerFramework.config file is in the same level as the web.config file. So, it can be either <episerver.framework configSource="EPiServerFramework.config" />  or <episerver.framework ... ><the settings></episerver.framework>.

    Note: Monitor this folder over time because there is no built-in cleanup.

  9. Open IIS > Edit Bindings, and assign a custom HTTPS binding (HTTPS is required for the integration service).
  10. Open the website to verify that it works.

Configuring OWIN startup

Service API uses OWIN-based authentication. This needs to be configured in the application’s Startup class.

Note: The Startup class should be in the root folder of your MVC web app. See also: App startup in ASP.NET Core.

The EPiServer.ServiceApi.Owin namespace contains the application builder extension methods required for this configuration. The following example sets up Service API to authenticate service calls using ASP.NET Membership.

Service API can also be set up to authenticate service calls using ASP.NET Identity. How to set up ASP.NET Identity in general and work with the Episerver UI is described in Episerver AspNetIdentity. The following example extends the Episerver UI ASP.NET call to the UseServiceApiIdentityTokenAuthorization method to configure Service API to use the same user type.

Note: With ASP.NET Identity configured, ensure you have a registered user account with appropriate permissions (for example, a member of the Administrators group).
Since the Service API uses the authorization provider specified in the Startup file, replace other uses of authorization server (like UseOAuthAuthorizationServer)  with IAppBuilder.UseServiceApiIdentityTokenAuthorization.
The CSR UI, currently in BETA, does not work properly with the Service API. This will be fixed in later Commerce versions.

Configuration modifications

Some settings are configured in the OWIN startup, while others are configured in web.config.

Token Timeout in Minutes

You can add this setting to the OWIN startup configuration. If omitted, the authorization server is configured without a setting, so the default OAuthAuthorizationServerOptions.AccessTokenExpireTimeSpan is used (20 minutes).

app.UseServiceApiMembershipTokenAuthorization(new ServiceApiTokenAuthorizationOptions
    AccessTokenExpireTimeSpan = TimeSpan.FromMinutes(60)

File Upload Maximum Size

To increase the maximum size that can be uploaded, change maxAllowedContentLength. Currently, the maximum file size is 2 GB.

Note: maxAllowedContentLength is in bytes, while maxRequestLength is in kilobytes.

Disable Attribute Routing

XMLService API automatically enables attributes routing.
If you already configured this, you can disable the Service API from automatically enabling attributes by adding an app setting. For information, see Attribute Routing in ASP.NET Web API 2.

  <add key="episerver:serviceapi:maphttpattributeroutes" value="false" />

Disable SSL requirement for request

By default, Service API requires secure connections both for authentication and for API calls. You can disable this with an app setting, for example, for a debug configuration in development.

  <add key="episerver:serviceapi:requiressl" value="false" />
Note: Live sites should not disable SSL.

Authentication tokens

To use any EPiServer.ServiceApi RESTful method, you must obtain an "OAuth 2 Bearer Token" to send with the request.

Sending request with tokens

Strongly typed catalog content types

Strongly typed catalog content types must be present in the context of a ServiceAPI site. If you install ServiceAPI to an existing website, this is solved automatically. However, if you install ServiceAPI as a standalone application, you must deploy the assembly that contains strongly typed catalog content types (and any dependencies of your assembly) to the ServiceAPI bin folder.


The following issues may arise when you set up the Service API.

  • Make sure there is a valid certificate on the server from a trusted certificate authority for the site.
  • Make sure all Service API requests are HTTPS.
  • You receive an error when trying to send a file to an import method. The Service API stores uploaded files in the AppDataPath set in the episerverframework.config file. Make sure the specified folder has the proper security permissions for the application pool identity.
  • Make sure there is a proper OWIN startup. You can disable this if there is a key on the appsettings.
    <add key="owin:AutomaticAppStartup" value="false" />
  • If controller resolution appears to not be working correctly, delete the temporary ASP.NET files and see if that fixes the problem.

Next steps

Do you find this information helpful? Please log in to provide feedback.

Last updated: Sep 14, 2018