View as Markdown
You’re viewing outdated documentation. View the latest Customer’s Canvas On-Premises documentation.

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

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

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

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

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

Downloads