---
title: "Authentication with Tokens"
canonical: https://customerscanvas.com/docs/cc6/authentication.htm
archived: true
applies_to:
  - product: "Customer's Canvas On-Premises"
  - product: "Design Editor"
    versions: ["6.15.0", "6.x (may differ)"]
---

**You’re viewing outdated documentation.** [View the latest Customer’s Canvas On-Premises documentation](https://customerscanvas.com/docs/on-premises/).

# Authentication with Tokens

**Applies to:** Customer's Canvas On-Premises; Design Editor 6.15.0, 6.x (may differ) · **Archived documentation**
 
When you need to send requests from a client, Customer's Canvas uses a token-based approach. It is especially important for the APIs where you are dealing with the user's private data, like their uploads (the [Gallery](https://customerscanvas.com/docs/cc6/web-api-for-private-gallery.htm.md) controller). This is how the idea works. Before you send requests to the API, which requires a userId, you need to generate a so-called token for each userId. After that, you just send this token along with the userId to protect the request.
 
You must use the **Auth** controller to manipulate tokens. It exposes the following endpoints:
 
|  Function |  Request type |  URL |
| --- | --- | --- |
   |  Create a user token |  POST |  `~/api/Auth/Users/{userId}/Tokens` |
 |  Get a token list |  GET |  `~/api/Auth/Users/{userId}/Tokens` |
 |  Update a token |  PUT |  `~/api/Auth/Tokens/{tokenId}` |
 |  Delete all user tokens |  DELETE |  `~/api/Auth/Users/{userId}/Tokens` |
 |  Delete a token |  DELETE |  `~/api/Auth/Tokens/{tokenId}` |
 |  Delete all tokens |  DELETE |  `~/api/Auth/Tokens` |
 
On this page, you can download the [code sample](https://customerscanvas.com/docs/cc6/samples/PrivateGalleryAPI.zip) demonstrating the work with the Private Gallery and Authentication API.
 
## Create a Token
  
To create a token, you can use the `~/api/Auth/Users/{userId}/Tokens` URL.
 
### URL Parameters
 
When you create a token, you can pass two optional URL parameters:
 
- **Seconds** defines the token expiration time. This parameter is `3600` seconds by default.
- **UpdateOnCall** allows for the extension of the token expiration time after the Web API calls. If `False`, this controller extends the token expiration time only through PUT requests. The Web API calls extend the expiration time for the amount in the **Seconds** value. By default, this parameter is `True`.

### Request Example
 
The following example illustrates how you can create an authentication token on the server side.
 
```
string createToken(string userId, string seconds, string updateOnCall)
{
    using (var client = new HttpClient())
    {
        var httpRequestMessage = new HttpRequestMessage();
        var uri = new Uri("https://example.com/cc/api/Auth/Users/" +
                  userId + "/Tokens?seconds=" + seconds + "&updateOnCall=" + updateOnCall);
        httpRequestMessage.RequestUri = uri;
        httpRequestMessage.Method = HttpMethod.POST;
        httpRequestMessage.Headers.Add("X-CustomersCanvasAPIKey", "UniqueSecurityKey");

        var response = await client.SendAsync(httpRequestMessage);
        var responseString = await response.Content.ReadAsStringAsync().Result;
        var jsonResult = JObject.Parse(responseString);
        return jsonResult["tokenId"];
    }
}
```
 
### Success Response
 
For example, you can get the following response when create a token for the **default** user.

```
Status Code: 200 OK
Content:
{
  "tokenId":"3840ca38-b6af-47b9-99bc-b2dd35282a59",
  "userId":"default",
  "expireTime":"2018-01-01T13:36:18.0252264",
  "originalSeconds":3600,
  "updateOnCall":true,
  "userData":null
}
```
 
### Error Response
 
You can obtain the following error response:

```
Status Code: 403 Forbidden
Content: Invalid Security Key
```
 
## Get a Token List
  
To retrieve a token list for a specific user, you can use the `~/api/Auth/Users/{userId}/Tokens` URL. This endpoint has no parameters.
 
### Request Example
 
```
string getTokens(string user, string seconds)
{
    using (var client = new HttpClient())
    {
        var httpRequestMessage = new HttpRequestMessage();
        var uri = new Uri("https://example.com/cc/api/Auth/Users/" + user + "/Tokens");
        httpRequestMessage.RequestUri = uri;
        httpRequestMessage.Method = HttpMethod.GET;
        httpRequestMessage.Headers.Add("X-CustomersCanvasAPIKey", "UniqueSecurityKey");

        var response = await client.SendAsync(httpRequestMessage);
        return response;
    }
}
```
 
### Success Response
 
For example, you can get the following response when get a token list for the **default** user.

```
Status Code: 200 OK
Content:
{
  "tokens":[{
    "tokenId":"cf85f762-96e9-4b5c-8c09-3a77f6a1de4a",
    "userId":"default",
    "expireTime":"2018-01-01T13:36:06.6510925",
    "originalSeconds":3600,
    "updateOnCall":true,
    "userData":"ccinternal"
  },
  {
    "tokenId":"3840ca38-b6af-47b9-99bc-b2dd35282a59",
    "userId":"default",
    "expireTime":"2018-01-01T13:36:18.0252264",
    "originalSeconds":3600,
    "updateOnCall":true,
    "userData":null
  }]
}
```
 
If a user has no active tokens, this endpoint returns the following response:

```
Status Code: 200 OK
Content:
{
  "tokens":[]
}
```
 
### Error Response
 
You can obtain the following error response:

```
Status Code: 403 Forbidden
Content: Invalid Security Key
```
 
## Update a Token
  
To update a previously generated token, you can use the `~/api/Auth/Tokens/{tokenId}` URL.
 
### URL Parameters
 
When you update a token, you can pass two optional URL parameters:
 
- **Seconds** extends the expiration time. If you skip this parameter, the token expiration time will be extended for the period specified at the time the token is created.
- **AdditionalUserId** allows you to enable a token for two users. When merging user accounts, you must pass the same **userId** as in the **setUserId** method.

### Request Example
 
```
string updateToken(string token, string seconds)
{
    using (var client = new HttpClient())
    {
        var httpRequestMessage = new HttpRequestMessage();
        var uri = new Uri("https://example.com/cc/api/Auth/Tokens/" +
                  token + "?seconds=" + seconds);
        httpRequestMessage.RequestUri = uri;
        httpRequestMessage.Method = HttpMethod.PUT;
        httpRequestMessage.Headers.Add("X-CustomersCanvasAPIKey", "UniqueSecurityKey");

        var response = await client.SendAsync(httpRequestMessage);
        return response;
    }
}
```
 
### Success Response
 
For example, you can get the following response when extend the `3840ca38-b6af-47b9-99bc-b2dd35282a59` token for `86400` seconds.

```
Status Code: 200 OK
Content:
{
  "tokenId":"3840ca38-b6af-47b9-99bc-b2dd35282a59",
  "userId":"default",
  "expireTime":"2018-01-02T13:26:16.3782821",
  "originalSeconds":3600,
  "updateOnCall":true,
  "userData":null
}
```
 
### Error Response
 
You can obtain the following error responses:
 
- ```
    Status Code: 403 Forbidden
    Content: Invalid Security Key
    ```
- ```
    Status Code: 404 Not Found
    Content: Token not found
    ```
 
## Delete Tokens
  
To delete tokens, you can use the following endpoints:
 
- `~/api/Auth/Users/{userId}/Tokens` - deletes all tokens for the **userId**.
- `~/api/Auth/Tokens/{tokenId}` - deletes **tokenId**.
- `~/api/Auth/Tokens` - deletes all tokens.

These endpoints have no parameters. The following example illustrates how you can delete tokens.
 
### Request Example
 
```
string deleteTokens(string user, string token)
{
    using (var client = new HttpClient())
    {
        var httpRequestMessage = new HttpRequestMessage();
        var url = "https://example.com/cc/api/Auth/";
        if (user == "")
        {
            if (token == "")
                // Delete all tokens for all users.
                url += "Tokens";
            else
                // Delete the token.
                url += "Tokens/" + token;
        }
        else
        {
            // Delete all tokens for the user.
            url += "Users/" + user + "/Tokens?UserId=" + user;
        }

        httpRequestMessage.RequestUri = new Uri(url);
        httpRequestMessage.Method = HttpMethod.DELETE;
        httpRequestMessage.Headers.Add("X-CustomersCanvasAPIKey", "UniqueSecurityKey");

        var response = await client.SendAsync(httpRequestMessage);
        return response;
    }
}
```
 
### Success Response

```
Status Code: 200 OK
```
 
### Error Response
 
You can obtain the following error responses:
 
- ```
    Status Code: 403 Forbidden
    Content: Invalid Security Key
    ```
- ```
    Status Code: 404 Not Found
    Content: Token not found
    ```
 
## See Also
  
### Manual
 
- [Web API](https://customerscanvas.com/docs/cc6/webapi.htm.md)
- [Private Image Gallery](https://customerscanvas.com/docs/cc6/web-api-for-private-gallery.htm.md)

### Downloads
 
- [Code sample](https://customerscanvas.com/docs/cc6/samples/PrivateGalleryAPI.zip)