Authentication with Tokens

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
Delete all user tokens DELETE ~/api/Auth/Users/{userId}/Tokens
Update a token PUT ~/api/Auth/Tokens/{tokenId}
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.

The 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/SimplePolygraphy/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"];
    }
}

The 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
}

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

The 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/SimplePolygraphy/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;
    }
}

The 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":[]
}

The Error Response

You can obtain the following error response:

Status Code: 403 Forbidden
Content: Invalid Security Key

Update a Token

To update a token, you can use the ~/api/Auth/Tokens/{tokenId} URL.

URL Parameters

When you update a token, you can pass an optional URL parameter: Seconds. This parameter 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.

The 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/SimplePolygraphy/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;
    }
}

The 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
}

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

The Request Example

C#
string deleteTokens(string user, string token)
{
    using (var client = new HttpClient())
    {
        var httpRequestMessage = new HttpRequestMessage();
        var url = "https://example.com/SimplePolygraphy/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;
    }
}

The Success Response

Status Code: 200 OK

The 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