HTTP API

Webtasks · Create

Sometimes all you want to do is create a new named webtask and get to work right away. Understanding the nuances of webtask token claims is overkill in many circumstances.

This endpoint gives you an easy way to get started creating and updating named webtasks.

Webtasks · List

Over time, it is easy to lose track of all of your named webtasks. This API gives you an easy way to page through them.

Webtasks · Delete

This endpoint allows you to delete named webtasks. Any accompanying storage will also be deleted. The request must be authenticated by specifying the A1 webtask token as the Authorization HTTP request header.

Webtasks · Storage

Sometimes your code needs just a little bit of persistent storage, and using a full database feels like too much. Webtask code can durably store a single JSON document up to 500KB in size using built-in storage. With simple get/set APIs and basic conflict detection, this is frequently all you need.

Storage APIs are only available from within named webtasks. They are not available from code submitted for execution as part of the HTTP POST request body.

Webtasks · Cache

Webtask runtime maintains in-memory cache of some webtask atrifacts that are normally durably persisted. This allows the runtime to reduce the latency of execution for frequently running webtasks. A good example of data that is cached is the compiled form of the webtask code itself. First execution of a given webtask requires the code to be fetched from the durable storage, but once that code is compiled into a JavaScript function, the function is cached in memory to speed up future invocations.

Webtask runtime takes care of purging the caches in certain situations to provide good developer experience. For example, when you update the code of a webtask, the previously compiled, cached versions of it are purged from the system. However, you can also explicitly request webtask cache to be purged using the HTTP APIs below.

Tokens · Create

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.

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, the Extend 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.

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

Tokens · Revoke

A webtask token can be revoked in order to prevent its future use to execute webtasks. When a webtask token is revoked, all webtask tokens directly or indirectly issued using it are also revoked. Revocation cannot be undone.

NOTE: revoked tokens may still be accepted for a short time after revocation (by default 2 minutes) due to caching of revocation status in the webtask runtime.

Tokens · Inspect

The webtask token inspect endpoint is used to inspect an existing webtask token. The request provides the authenticating webtask token A1 in the headers and the token for inspectionA2 in the query parameters.

Inspecting tokens is useful when you are storing derived tokens on behalf of your users in a multi-tenant setup. Inspecting tokens provides a mechanism to securely inspect the code and/or secrets that are embedded in a webtask that would otherwise be impossible to determine.

Modules · List

Before a webtask can take a dependency on an NPM module, the NPM module must be registered with the platform. Because several versions of the same NPM module can be registered, a specific version of the NPM module must also be specified during registration. Registering NPM modules allows the platform to download and install the NPM module beforehand, ensuring that the dependency is available whenever the webtask executes.

To get the versions of a given NPM module that have been registered with the platform, use the following endpoint.

Modules · Ensure

Before a webtask can take a dependency on an NPM module, the NPM module must be registered with the platform. Because several versions of the same NPM module can be registered, a specific version of the NPM module must also be specified during registration. Registering NPM modules allows the platform to download and install the NPM module beforehand, ensuring that the dependency is available whenever the webtask executes.

To ensure that a given version of a given NPM module has been registered with the platform, use the following endpoint. If the given version of the NPM module has not yet been registered, it will be queued for registration with the platform.