---
title: Install versions 6 and 7
slug: commerce-connect-15/service-api/installation-and-configuration
docTags: 
createdAt: 2026-07-22T14:38:28.000Z
---

## Prerequisites

[Install Optimizely updates](docId\:VuiU-K4aAR6ISGicFg4lk)  through the NuGet Package Manager in Visual Studio.

## Install Service API

1. Open Visual Studio and follow the steps below.
2. Right-click on the project and choose **Properties**.
3. Set the target framework for your project to **.NET 4.0** or higher.
4. Select **Tools > NuGet Package Manager > Manage NuGet packages for Solution...** You can also right-click on the solution references.
5. Click **Settings** to create a source pointing to the Optimizely NuGet feed.
6. Open the Online section and select the source you just created.
7. Install [EPiServer.ServiceApi](https://nuget.optimizely.com/package/?id=EPiServer.ServiceApi) and [EPiServer.ServiceApi.Commerce](https://nuget.optimizely.com/package/?id=EPiServer.ServiceApi.Commerce).
8. Install [EPiServer.OpenIDConnect](https://nuget.optimizely.com/package/?id=EPiServer.OpenIDConnect) for token authentication. You can also use other authentication schemes.

## Configure authentication

See API authentication for more detailed information.  The following example shows how to configure open connect for Service API.

```csharp
services.AddOpenIDConnect<SiteUser>(
  useDevelopmentCertificate: true,
  signingCertificate: null,
  encryptionCertificate: null,
  createSchema: true,
  configureOptions =>
  {
    {
      //options.RequireHttps = !_webHostingEnvironment.IsDevelopment();
      var application = new OpenIDConnectApplication()
      {
        ClientId = "postman-client",
        ClientSecret = "postman",
        Scopes =
        {
          ContentDeliveryApiOptionsDefaults.Scope,
          ContentManagementApiOptionsDefaults.Scope,
          ContentDefinitionsApiOptionsDefaults.Scope,
          ServiceApiOptionsDefaults.Scope
        }
      };                  

      // Using Postman for testing purpose.
      // The authorization code is sent to postman after successful authentication.
      application.RedirectUris.Add(new Uri("https://oauth.pstmn.io/v1/callback"));
      configureOptions.Applications.Add(application);                    
    },
    configureSqlServerOptions: null);                
  }
services.AddServiceApiAuthorization(OpenIDConnectOptionsDefaults.AuthenticationScheme);  
```

If you use `OpenIdConnect` and client credentials grant type, add the application to the permissions to functions for read and or write access.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/mZdbmWBjaBGgUD5lIY1lu-20260722-143929.png)

If you use another authentication scheme, ensure the claim identity has the correct roles defined for read and write access to the permissions to functions for Service API.

### Disable SSL requirement for request

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

```csharp
{
  "EPiServer" : {
    "ServiceApi" : {
      "RequireSsl":false
    }
  }
}

public void ConfigureServices(IServiceCollection services)
{
  services.Configure<ServiceApiOptions>(x => x.RequireSsl = false);
}
```

:::hint{type="info"}
**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.

```csharp
using (var client = new HttpClient())
{
  client.BaseAddress = new Uri("https://mysite.com/");
  var fields = new Dictionary<string, string>
  {
    { "grant_type", "client_credentials" },
    { "client_id", clientIdValue },
    { "client_secret", clientSecretValue },
    { "scope", ServiceApiOptionsDefaults.Scope}
  };
  var response = client.PostAsync("/api/episerver/connect/token", new FormUrlEncodedContent(fields)).Result;
  if (response.StatusCode == HttpStatusCode.OK)
  {
    var content = response.Content.ReadAsStringAsync().Result;
    var token = JObject.Parse(content).GetValue("access_token");
  }
}			
    
POST /episerverapi/token HTTP/1.1
Host: mysite.com
User-Agent: Mozilla/5.0 (Windows NT 6.2; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/32.0.1667.0 Safari/537.36
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 29
Accept-Encoding: gzip
grant_type=password
username=test
password=test
```

```csharp
using (var client = new HttpClient())
{
  client.BaseAddress = new Uri("https://mysite.com/");
  var fields = new Dictionary<string, string>
  {
    { "grant_type", "password" },
    { "client_id", clientIdValue },
    { "client_secret", clientSecretValue },
    { "scope", ServiceApiOptionsDefaults.Scope },
    { "username", userNameValue },
    { "password", passwordValue }
  };
  var response = client.PostAsync("/api/episerver/connect/token", new FormUrlEncodedContent(fields)).Result;
  if (response.StatusCode == HttpStatusCode.OK)
  {
    var content = response.Content.ReadAsStringAsync().Result;
    var token = JObject.Parse(content).GetValue("access_token");
  }
}			
    
POST /episerverapi/token HTTP/1.1
Host: mysite.com
User-Agent: Mozilla/5.0 (Windows NT 6.2; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/32.0.1667.0 Safari/537.36
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 29
Accept-Encoding: gzip
grant_type=password
username=test
password=test
```

```csharp
HTTP/1.1 200 OK
Status: 200 OK
Content-Type: application/json; charset=utf-8
  ...
Content-Encoding: gzip
Content-Length: 140
{"token_type":"bearer","access_token":"AAAA%2FAAA%3DAAAAAAAA"}
```

You need these **headers** and **keys** to retrieve a token in Postman:

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/eAZjtV_FAFcqktVeaaYkw-20260722-143929.png)

For Service API 6

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/AGEVz7P2WOtDdQ9DJ4EfF-20260722-143929.png)

For Service API 7

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/tWD9LvRQoDJtB62lIBoAr-20260722-143929.png)

**Sample cURL Command - Service API 6**

```bash
curl --location --request POST 'https://localhost:5000/api/episerver/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=postman-client' \
--data-urlencode 'client_secret=postman' \
--data-urlencode 'scope=epi_service_api'
```

**Sample cURL Command - Service API 7**

```bash
curl --location --request POST 'https://localhost:5000/api/episerver/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=postman-client' \
--data-urlencode 'client_secret=postman' \
--data-urlencode 'scope=epi_service_api' \
--data-urlencode 'username=the-username' \
--data-urlencode 'password=the-password'
```

### Send request with tokens

```csharp
using (var client = new HttpClient())
{
  client.BaseAddress = new Uri("https://mysite.com/");
  client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token.ToString());
  var content = new MultipartFormDataContent();
  var filestream = new FileStream(path, FileMode.Open);
  content.Add(new StreamContent(filestream), "file", "Catalog.zip");
  var response = client.PostAsync("/episerverapi/commerce/import/catalog", content).Result;
  if (response.StatusCode == HttpStatusCode.OK)
  {
    var returnString = response.Content.ReadAsStringAsync().Result;
    returnString = returnString.Replace("\"", "");
    Guid taskId = Guid.Empty;
    Guid.TryParse(returnString, out taskId);
  }
}
```

### 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.

## Troubleshoot Service API

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

- Ensure there is a valid certificate on the server from a trusted certificate authority for the site.
- Ensure all Service API requests are HTTPS.

There is no rate limit set for the Service API.

See also [Service API REST API reference](https://docs.developers.optimizely.com/commerce/v1.3.0-service-api-developer-guide/reference/service-api-reference-guides).

## Permissions for functions

You can configure the read and write functions of the Service API in the Permissions for Functions area.

1. Go to **Admin > Access Rights > Permissions for Functions**.
2. Select **ReadAccess** or **WriteAccess** under EPiServerServiceApi, depending on the desired permission.
   For instance, you may want to give access for reading or updating the catalog via endpoint, such as the following endpoints:
   `/episerverapi/commerce/export/catalog/`
   `/episerverapi/commerce/import/catalog/`
3. Add the User or the ClientId value that has been set up in the middleware configuration of the ServiceAPI.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/JDc0gWt5ZFXo-KArdysHr-20260722-143929.png" size="100" caption="screenshot-bro-d-cl-02.niteco.dev-2022.05.24-10_25_30.png" isUploading="false" darkWidth="1260" darkHeight="510" width="1260" height="510" showCaption="false"}