{jwtencode:key:username:password:lifetime:add_validity}

Description

Authenticates a user by username and password and, on success, returns a signed JSON Web Token (JWT) that the user can send back in an Authorization Bearer header to prove their identity. The token is signed with HS256 using your secret key and carries the user id (sub), an issued-at time (iat) and an expiry time (exp). If the secret key, username or password is missing, or authentication fails, the command returns an empty string. The lifetime parameter sets how many seconds the token stays valid; left empty it defaults to 86400 (one day). The optional add_validity parameter is an AA expression evaluated for the authenticated user and stored in the token as an extra check, letting you invalidate older tokens later (for example on logout); it only works for Reader Management users. Decode and verify a token with jwtdecode. Output is a fresh signed token on every call, so jwtencode is never a deterministic test.

Parameters

key required

The secret signing key. The same key must be passed to jwtdecode to verify the token; keep it private. Required - an empty key returns an empty string.

username required

The login name to authenticate. Combined with password and checked against the AA permission system (admin users or Reader Management users). Required.

password required

The password for username. If the username and password do not authenticate, the command returns an empty string. Required.

lifetime optional default 86400

How many seconds the token stays valid, counted from now. Left empty (or 0) it defaults to 86400, one day. The value is stored in the token as the exp (expiry) claim.

add_validity optional

Optional. An AA expression evaluated for the authenticated user (as item:USERID:add_validity) and stored in the token as the aaValid claim. jwtdecode re-evaluates it and rejects the token if the value changed, letting you invalidate old tokens (for example by updating a logout-time field on logout). Works only for Reader Management users; used with a regular admin it returns an empty string.

Examples

test[{jwtencode:}]
Expected[]
Actual[]
With no secret key the command can never sign a token, so it returns an empty string. The square brackets only frame the empty result.
test[{jwtencode:my-secret-key}]
Expected[]
Actual[]
A key is given but username and password are empty, so there is nobody to authenticate and the result is empty.
test[{jwtencode:my-secret-key:editor}]
Expected[]
Actual[]
The password (third parameter) is empty, so authentication cannot run and the result is empty.
test[{jwtencode:my-secret-key:nosuchuser:wrongpass}]
Expected[]
Actual[]
Username and password are both present but do not match any account, so authentication fails and the command returns an empty string. This is how a wrong login is signalled - no token, not an error.
virtual{jwtencode:my-secret-key:{qss:email}:{qss:password}}
Expected(a signed JWT, e.g. eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI...)
The real-world shape: take an email and password posted to the page (read here with qss) and sign a token for that user. With valid credentials this returns a long signed token string; the default lifetime of one day applies. The output changes on every call (it embeds the current time), so this is illustrative, not a test.
virtual{jwtencode:my-secret-key:{qss:email}:{qss:password}:3600}
Expected(a signed JWT that expires in 3600 seconds)
The fourth parameter sets the lifetime in seconds. Here 3600 makes the token expire after one hour instead of the default one day. With valid credentials this returns a signed token whose exp claim is one hour ahead.
virtual{jwtencode:my-secret-key:{qss:email}:{qss:password}:3600:_#EXITTIME}
Expected(a signed JWT carrying the aaValid claim; Reader Management users only)
The fifth parameter is an AA expression evaluated for the user and stored in the token. Passing the EXITTIME alias means jwtdecode will later compare it against the users current end-time field; updating that field on logout invalidates every token issued before. Works only for Reader Management users; with a regular admin the command returns an empty string.
← All expressions