Authentication

• 3 minutes to read

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 config file:

<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:

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

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 to False.

In load balancing scenarios, a 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 file.

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

  <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:

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