Saltar al contenido principal

AJWT

Algho JSON Web Token (in short AJWT) are a reliable and secure way to share your users' informations with Algho.

To configure Algho with a custom AJWT you can populate the AJWT param inside the integration script or use the algho.setAJWT("...") method:

// configure AJWT when loading Algho
tag.setAttribute("ajwt", "...");
// or dinamically when Algho is available
algho.setAJWT("...");

You can use AJWT to enrich and personalize every kind of message coming from Algho by simply inserting a placeholder. For example, the placeholder @@AJWT_name@@ will resolve and return the value of payload['name']. Both strings and numbers will be shown to the user, but arrays and objects won't be resolved. You can also use AJWT on your web services, for each request the valid token will be sent under the algho-json-web-token header.

Two kind of AJWT are currently supported: unsigned and signed tokens. Encrypted tokens may be supported in the future. As per the JWT standard, the AJWT must be composed of three section separed with dots. The first section contains the headers, the second section contains the payload, the third section contains the signature. All the standard JWT claims are supported. During the validation of the token both exp (expiration time) and nbf (not before time) will be taken into account. To address the problem of servers' clock synchronisation a skew of 5 minutes is applied, so the token will be valid 5 minutes before the nbf and 5 minutes after the exp. In addition to the standard claims expected for JWT, Algho JSON Web Token require a payload claim that will be used by Algho. The payload claim must be a valid JSON object.

This is an example of a valid unsigned AJWT. Note that the alg header is "none" and the signature is missing. The trailing dot is important and must not be removed. This is an example of a valid signed AJWT. If you configure a public key, be sure that the length of the key is enough for the specified alg used.

Algho will only use valid AJWT token. An AJWT is considered valid if:

  1. the exp (expiration time) and nbf (not before time) can be omitted; but if present they MUST be between a 5 minutes skew of the current time;
  2. the AJWT is an unsigned token and no public keys have been provided for the current bot;
  3. the AJWT is a signed token, but no public keys have been provided for the current bot;
  4. the AJWT is a signed token, and the signature of the token matches the one produced by one of the public keys provided.

To add your public key to a bot, open the actions menu for a bot and select "Public Keys", then click the "Add" button and specify the name and the base64 value of the public key. A bot can have multiple public keys configured. A token will be considered valid if one or more public key produce the same signature. If the algorithm used to sign the AJWT is based on a single shared secret key (such as HMAC) then the secret key must be configured. If the algorithm used to sign the AJWT is based on a key pair (such as RSA or ECDSA) then the public key must be configured. You can't configure the private key to verify a token signed with an asymmetric algorithm. EdDSA signed tokens are not supported by the JWT standard.