Login

writeJwt(userinfo) Last updated: 22. Jun 2026

API only function

The writeJwt function generates a signed JWT (JSON Web Token) and writes it as a secure session cookie (access_token) to the user's browser. Write a NULL value to log the user out.

See also: deleteJwt denyAccess logOut flagActivity getProfilePictureUrl Custom JWT login example

Parameters

Name Type Description
userinfo object

A JSON object with all necessary info about user.
Will be stored in an encrypted cookie.

Returns

True if successful.

Security details

The token is signed and validated server-side using HMAC-SHA256 with a per-site secret key (PublishedFolder.JwtSecret, 64 hex characters, auto-generated on first use and stored in the database, never exposed to the client) — so it cannot be forged without the server key.

The cookie is written with the following flags: HttpOnly=true (not accessible from JavaScript), Secure=true (only sent over HTTPS), and SameSite=Lax (protects against CSRF on cross-site POST/subrequests). On every request the token is decoded and its HMAC recomputed with the server key; if the signature does not match (tampered/forged token) it is rejected.

deleteJwt mirrors the Secure+SameSite flags so the cookie is overwritten consistently on logout.

Example

Code example (JS)

JS is normal JavaScript either running in the browser or on the Docly™ server. 
// Issue a session JWT cookie for the user
docly.writeJwt({ "username": username, "access": "admin" });

// In any other API function, read the cookie back via request.Jwt
if (request.Jwt.access != "admin")
    return docly.denyAccess();

// To log the user out again, write a NULL value (or call deleteJwt)
docly.writeJwt(null);


// *********************************
// A full login-flow example:
// #/API/login.js
export default (username, passwordHash) => {

    let user = docly.getFile("#/Users/" + username);

    if (!user || user.PasswordHash !== passwordHash) {
        // Tick the brute-force counter for this IP
        let blocked = docly.flagActivity();
        if (blocked) {
            return { error: "Too many failed attempts. Try again later." };
        }
        return { error: "Invalid username or password." };
    }

    // Success — issue the session JWT
    docly.writeJwt({
        username: user.Username,
        access: user.AccessLevel
    });
    return { success: true };
}


// The matching login page is a plain static HTML form that POSTs to /API/login.
// Keep it free of #...# expressions — hash templates are cached and would leak
// per-user data across requests.