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

# Auth tokens

> When you need to send requests from a client, Design Editor 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/on-premises/design-editor/apis/user-uploads.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](#create-a-token) | POST | **~/api/Auth/Users/{userId}/Tokens** |
| [Get a token list](#get-a-token-list) | GET | **~/api/Auth/Users/{userId}/Tokens** |
| [Update a token](#update-a-token) | PUT | **~/api/Auth/Tokens/{tokenId}** |
| [Delete all user tokens](#delete-tokens) | DELETE | **~/api/Auth/Users/{userId}/Tokens** |
| [Delete a token](#delete-tokens) | DELETE | **~/api/Auth/Tokens/{tokenId}** |
| [Delete all tokens](#delete-tokens) | DELETE | **~/api/Auth/Tokens** |

On this page, you can [download the code sample](pathname:///files/PrivateGalleryAPI.zip) demonstrating how to 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.

```cs title="Create a Token"
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.

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

```text
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

```cs title="Get a Token List"
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.

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

```text
Status Code: 200 OK
Content:
{
  "tokens":[]
}
```

### Error Response

You can obtain the following error response:

```text
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

```cs title="Update a Token"
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.

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

-   ```text
    Status Code: 403 Forbidden
    Content: Invalid Security Key
    ```

-   ```text
    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

```cs title="Delete Tokens"
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

```text
Status Code: 200 OK
```

### Error Response

You can obtain the following error responses:

-   ```text
    Status Code: 403 Forbidden
    Content: Invalid Security Key
    ```

-   ```text
    Status Code: 404 Not Found
    Content: Token not found
    ```