Webtask

Documentation

HTTP API: Creating Webtask Tokens

Create restricted tokens for individual users or applications

For customized documentation and ready to run samples, please log in.

The webtask token request endpoint is used to issue a new webtask token. Request provides the authenticating webtask token A1 and a JSON structure with token request parameters. Response contains newly issued token A2.

Issuing new tokens is useful when you want to provide your application or specific user with a restricted capability of running webtasks. For example, you can restrict the webtask token to only execute code from a specific URL, or specify secret parameters that will be passed to that code at execution time.

HTTPS POST /api/tokens/issue
Content-Type: application/json        

The request must be authenticated by specifying the A1 webtask token as the key URL query parameter or with the Authorization HTTP request header as described above. The content type of the request must be application/json. The body of the request must contain a JSON object representing the intended restrictions of the A2 token to be issued. The object can specify the following properties (all of them optional):

ten

is a restriction on the webtask container name in which webtask requests using the newly issued token can execute code. You can provide a regular expression (e.g. /^foo[0-9]$/) or a comma-delimited list of string literals (e.g. foo1,foo2).

jtn

is an optional name of the webtask to create. For requests that specify this parameter, webtask cluster will durably store the issued webtask token and assign it a logical name, or an alias, of the form {ten}/{jtn}. This allows later execution of this webtask using shorthand URLs of the form https://{webtask_domain}/api/run/{ten}/{jtn}. If jtn is specified, the ten parameter must be a simple string literal.

jtnm

is an optional array of strings limiting the names of the webtasks the token can be used to perform management operations on. Tokens with ten and jtnm claims can be used to limit bearer's management capabilities within the scope of a single webtask container.

nbf

is a not before time restriction in Unix time.

exp

is a not after time restriction in Unix time.

host

is the custom domain name webtasks can be called with. This parameter requires also the parameter ten, since you can only set a custom domain when creating tokens for a specific container. Setting a value for host while not setting ten will result in an error. When host is set, the webtask runtime will validate whether the caller owns the custom domain. This validation is done by checking if a TXT record exists in the DNS of the specified custom domain. This TXT record should list the webtask container name (the value of property ten) and is a statement from the domain owner, permitting webtasks called over that custom domain name to run in a specific webtask container. An example of how TXT records look like in CloudFlare DNS management system:

cloudfare-dns-txt-records

In this example we have associated our custom domain (host = serverless.host) with two containers (ten = auth0, tjanczuk). So the syntax of the TXT record should be: webtask:container:{ten} , where {ten} is the same as the ten value specified in the token creation request.

If the ownership is not validated then an error will be displayed prompting the user to add a DNS record with type TXT and value webtask:container:{ten}.

meta

is used to specify metadata (a set of string key / value pairs) for a token. The parameter can only be specified if the jtn parameter is also specified, which means a named webtask is being upserted.

HTTPS POST /api/tokens/issue
{
  ...,
  meta: {
    name: 'restrict-webtasks',
    description: 'This webtask token executes code only from URL www.example.com'
  }
}

pb

is a flag indicating whether webtask runtime should automatically process request bodies of requests with application/json or application/x-www-urlformencoded content type. If set to 0, request body will not be parsed. If set to 1, request body will be processed and stored in the context.body attribute.

If set to 2 or left unset (default), request body will be processed depending on the arity of the webtask function: for (context, cb) function signature, request body will be parsed and stored in the context.body attribute, and for (ctx, req, res) function signature, requst body will be left unread.

mb

is a flag indicating whether body data processed when pb is set to 1 should be merged into context.data in apition to being stored in context.body. If set to 1, and if the body of the request represents a JavaScript object, properties of that object will be aped to context.data, unless they already exist there. It only makes sense to set mb when pb is also set.

dd

is the maximum depth of token issuance the issued token will be able to perform. If token T1 has depth 2, it means it can be used to issue token T2 with depth 1; token T2 can be used to issue token T3 with depth 0; and token T3 cannot be used to issue any more tokens. Default depth is 1. You cannot request value of dd that is equal or larger than the authenticating token.

dr

is a flag indicating whether the issued token can revoke itself with a call to the revocation HTTP API. If the dr flag is absent (the default) or set to 0, the issued token can revoke itself. Set dr=1 to prevent the token from revoking itself. This may be useful if you plan to ship the issued token in multiple applications or to multiple users, some of whom cannot be trusted with the revocation decision.

pctx

is an JSON object with string properties which specifies parameters that will be provided to the webtask code at the time of execution. The properties will be signed and protected from interference but not encrypted - anyone with access to the newly issued token A2 can read their value.

ectx

is an JSON object with string properties which specifies parameters that will be provided to the webtask code at the time of execution. The properties will be signed and encrypted, therefore making them tamper-proof and inaccessible from third parties, including anyone with access to the newly issued A2 token. This is a convenient mechanism to pass secrets to the webtask code.

url

is the URL of the webtask code to execute. Webtask requests authenticated with the newly issued A2 token that contains the url property must not specify the code to execute at all. The webtask cluster will obtain the code from the URL specified in url with HTTP GET. This is a mechanism you can use to fix the code a given token can execute. The urlparameter is mutually exclusive with the code parameter.

code

is the literal code of the webtask to execute. Webtask cluster will store the webtask code using internal storage facilities and issue an A2 token that specifies the url property indicating its location. The code parameter is mutually exclusive with the url parameter.

ls, lm, lh, ld, lw, lo

are the per second, minute, hour, day, week, and month (respectively) rate limits applied per webtask container. Only limits that are specified are applied. All specified limits must be positive integers. When issuing tokens, container rate limits of the authenticating token are propagated to the issued token.

lts, ltm, lth, ltd, ltw, lto

are the per second, minute, hour, day, week, and month (respectively) rate limits applied per webtask token. Only limits that are specified are applied. All specified limits must be positive integers. Unlike in case of container limits, token limits are not propagated from the authenticating token to the issued token during token issuance. This means every token can have its own token rate limits that are determined by the immediate issuer.