Auth tokens

• 4 minutes to read

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

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