Webtask

Documentation

Issuing tokens from webtask code

Create new webtask tokens within webtask code

Overview

If you have a webtask token, you can use it to create another webtask token with restricted or more specific permissions. For example, you can create a webtask token that can only execute very specific webtask code, or one that has rate limits associated with it. Such tokens can then be propagated to individual applications under your control or users of your application.

The token issuance HTTP API allows you to create such tokens using any HTTP client. However, there is a set of programmatic APIs available from within executing webtask code that make the token issuance easy.

Token

The webtask token that was used to authorize execution of the running webtask code is available through the ctx.token property:

module.exports = function(ctx, cb) {
    console.log(ctx.token);
    cb(null, "Hello");
}
The token can be used directly to authorize calls to the token issuance HTTP API. The webtask token is available in the context only in the following circumstances:

  • the token which authorized webtask code execution restricted the executing code by providing its url,
  • the caller of the webtask execution HTTP API explicitly requested the authorization webtask token to be shared with the webtask code using the webtask_share_token URL query paramater.

Creating new webtask tokens

You can create new webtask tokens within webtask code using the ctx.create_token API. In the simplest form, you only need to specify the URL of the webtask code the new webtask token will allow to execute:

module.exports = function(ctx, cb) {
    ctx.create_token(
        'https://example.com/my/webtask/code.js', 
        function (error, new_token) {
          console.log('New token is:', new_token);
          cb(null, "OK");
        });
}        

Creating new webtask tokens with secrets

You can create new webtask token that will execute specific webtask code, and securely provide this code with secrets (e.g. connections strings, API keys, etc.):

module.exports = function(ctx, cb) {
    ctx.create_token({
      code_url: 'https://example.com/my/webtask/code.js', 
      secrets: {
        my_mongourl: '{your_mongodb_url}',
        my_twilio_key: '{your_twilio_key}'
      }
    }, function (error, new_token) {
      console.log('New token is:', new_token);
      cb(null, "OK");
    });
}        

Creating webtask token URLs

Webtask token URL is simply a URL to a webtask cluster's code execution API that is prepopulated with the authorization webtask token. Webtask token URLs can be directly used in web browsers, and are a convenient way of serving small web applications.

Webtask token URL creation API ctx.create_token_url is a simple wrapper around the ctx.create_token API, and accepts all the same parameters, e.g.:

module.exports = function(ctx, cb) {
    ctx.create_token_url({
      code_url: 'https://example.com/my/webtask/code.js', 
      secrets: {
        my_mongourl: '{your_mongodb_url}',
        my_twilio_key: '{your_twilio_key}'
      }
    }, function (error, webtask_url) {
      console.log('Webtask URL is:', webtask_url);
      cb(null, "OK");
    });
}        

Advanced token creation

There is a number of additional options that token creation API supports:

module.exports = function(ctx, cb) {
    ctx.create_token({
        // URL of the webtask code to execute. 
        // Default: that of ctx.token.
        code_url: 'https://example.com/my/webtask/code.js', 

        // The webtask token to authorize call to the token issuance API. 
        // Default: ctx.token.
        issuer_token: null,

        // The URL (scheme, host, port) of the webtask cluster that will
        // issue the new webtask token. 
        // Default: same cluster as the one where webtask code runs.
        issuer_url: null,

        // Webtask container name limitation for new webtask token.
        // Default: same as the webtask container this code runs in.
        container: null,

        // Time validity of the newly issued token. 
        // This is a Date, a string in RFC2822 or ISO8601 format, or
        // a number preceeded with + sign to indicate "minutes from now".
        // Default: same as the ctx.token.
        not_before: null,
        expires: null,

        // Set to 1 to prevent automatic parsing of the request body
        // when the webtask token is used to execute webtask code. 
        // Default: 0
        disable_parse_body: 0,

        // Set to 1 to prevent merging of a parsed body content into 
        // ctx.data property, which contains parameters from the 
        // webtask token as well as URL query parameters. 
        // Default: 0
        disable_merge_body: 0,

        // The depth of the token issuance chain the newly issue webtask
        // token will be able to create.
        // Default: 0 (i.e. the newly issued token cannot issue other tokens)
        delegation_depth: 0,

        // Set to 1 to prevent the newly issued webtask token to self-revoke. 
        // Default: 0
        disable_self_revocation: null,

        // A hash of key value pairs that will be stored in the 
        // webtask token and protected from tampeting and spoofing.
        // Good place to provision secrets (e.g. connection strings)
        // to webtask code.  
        // Default: null.
        secrets: {
          key1: "value1",
          key2: "value2"
        },

        // Similar to secrets, but these parametrs will not be encrypted. 
        // Default: null.
        params: {
          key1: "value1",
          key2: "value2"              
        },

        // The rate limits that will be applied to the newly issued token
        // specified per second, minute, hour, day, week, and month, respectively.
        // Default: none.
        token_limits: {
          ls: null, 
          lm: null, 
          lh: null, 
          ld: null, 
          lw: null, 
          lo: null
        },

        // Similar to token rate limits, but applied at the scope of the
        // webtask container the code is running in.
        // Default: none.
        container_limits: {
          ls: null, 
          lm: null, 
          lh: null, 
          ld: null, 
          lw: null, 
          lo: null
        }
    }, function (error, new_token) {
      console.log('New token is:', new_token);
      cb(null, "OK");
    });
}