---
title: "Authentication | Customer's Canvas On-Premises"
canonical: "https://customerscanvas.com/docs/on-premises/design-editor/apis/auth/"
---

# Authentication

> There are two security models used in Design Editor APIs - _API Keys_ and _user tokens_. Both of them are described below in this artile.

## Using API Keys

With API Key security model, you need to include a special key as a `X-CustomersCanvasAPIKey` HTTP header to each request protected by the API Key. This is a most of our APIs.

If you are using on-premise instance of Design Editor, you can specify an API key through the [AppSettings.config](https://customerscanvas.com/docs/on-premises/design-editor/it-ops/config-backend/appsettings.md) file:

```xml
<appSettings>
    <add key="ApiSecurityKey" value="MyLongAndSecureApiKey123" />
</appSettings>
```

It is recommended to generate secure random alphanumeric string at least of 16 characters.

If you are using Design Editor installed as a part of Customer's Canvas Hub cloud environment, the API key is already pre-configured. You can get it through BackOffice application (Settings -> General).

Once you have your API Key, send it along with each API call like this: 

```curl
POST <app URL>/api/Preview/GeneratePreview
X-CustomersCanvasAPIKey: MyLongAndSecureApiKey123
{
    ...
}
```

## Using Auth Tokens

This security model is used with APIs which deal with data created by the end users, such as [private image gallery](https://customerscanvas.com/docs/on-premises/design-editor/apis/user-uploads.md). In other word, it is required when you need to include the user ID along with the other data to your requests.

The idea is that before you start using such APIs, you need to register a user ID and receive a corresponding _token_ with a help of [Auth tokens](https://customerscanvas.com/docs/on-premises/design-editor/apis/auth-tokens.md) API. The same API is used to refresh or revoke these tokens. 

Once you have a token, you should include it as `X-CCToken` header, like this: 

```bash
GET <app URL>/api/Gallery/Private/{userId}/files/
X-CCToken: 87d866cce2b644cebc90ca05b8db5d34
```

This token-based authentication is built into the Design Editor application and used when the editor is running as a single instance. User and token data is stored in the built-in SQLite database. The database file is located in **/App_Data/ccdb.sqlite**.

You may turn off the token-based authentication and use a regular API key authentication. To do it, set the `SecureModeEnabled` param in [AppSettings.config](https://customerscanvas.com/docs/on-premises/design-editor/it-ops/config-backend/appsettings.md) to `False`. 

In load balancing scenarios, a [TokenService](https://customerscanvas.com/docs/on-premises/design-editor/it-ops/install/load-balancing.md#authentication-via-tokenservice) must be used. This is a separate service for authentication operations in the Design Editor, which deployed as a separate web application.

## Configuring protection

Customer's Canvas allows you to enable or disable authentication and HTTPS enforcement for a single request. You can define your security policy in the [AuthSettings.config](https://customerscanvas.com/docs/on-premises/design-editor/it-ops/config-backend/auth.md) file. 

This is an XML file with the root note `<AuthSettings>`. The configuration is specified with child `<route>` nodes like this: 

```xml
  <route 
    name="Rendering API: proofs and hires" 
    path="api/Rendering/{*}" 
    methods="GET, POST" 
    authRequired="false" 
    unsafeHttpMode ="enabled"
  />
```

Its attributes are the following: 

- `name` - a description of a route. Should be unique and, ideally, descriptive enough for a better config readability.
- `path` - a route template. It may include `{*}` placeholder (for any substring), `{action}` for an action name inside a controller, or `{varName}`, where `varName` depends on API (e.g. `{stateId}` or `{userId}`).
- `method` - applicable HTTP verbs.
- `authRequired` - whether to check API key for a specified route.
- `unsafeHttpMode` - whether to allow sending requests through HTTP. By default, all APIs require HTTPS. 

For example, to disable checking the security key for the **api/ProductTemplates/Designs** and **api/ProductTemplates/Mockups** endpoints, you can set `authRequired` to `false` for these routes:

```xml
<route
    name="Getting the list of Designs"
    path="api/ProductTemplates/Designs"
    methods="GET"
    authRequired="false"
/>

<route
    name="Getting the list of Mockups"
    path="api/ProductTemplates/Mockups"
    methods="GET"
    authRequired="false"
/>
```

Note, the order of routes matters. They are processed from the beginning to the end, which means that more general routes should go first. For example, the `api/ProductTemplates/{*}` should go earlier than `api/ProductTemplates/designs`, otherwise it will be overlapped.