Authentication setup

Authentication requires readers to sign in before they can open your documentation. You can protect the whole site, or leave some pages public while the rest stay private.

Configure authentication in the dashboard under Settings → Authentication.

Choose an authentication method

Saving visibility or an authentication method starts a deployment. Wait for that build to finish before you test sign-in on the published site.

Configure authentication

Password

Password authentication controls access only. It does not track individual readers or support group-based page rules.

Password prerequisites

• Your security requirements allow sharing passwords among readers.

Password setup

After the deployment finishes, visitors must enter a password to open protected pages.

Workspace

Workspace authentication limits the site to active members of your Velu workspace. Readers sign in with their Velu account.

Workspace prerequisites

• Everyone who needs access is an active, email-verified member of your workspace. Manage members under Settings → Members.

Workspace setup

OAuth 2.0

OAuth prerequisites

• An OAuth or OIDC server that supports the Authorization Code flow.
• Optional: an HTTPS user-info endpoint, or group claims in the ID or access token, if you need group-based page access.

OAuth setup

https://YOUR-DOCS-HOST/login/oauth-callback

Provider URLs must use HTTPS. You cannot override protocol fields such as state, redirect_uri, or PKCE parameters.

JWT

JWT prerequisites

• A backend that can authenticate users and sign EdDSA JWTs.
• One or more login URLs readers can open from the docs site.

JWT setup

When one login URL is configured, unauthenticated readers go there directly. With two or more named URLs, they choose a destination first. Velu forwards a relative redirect query parameter so you can return them to the page they requested.

JWT example

import time
import jwt  # PyJWT

DOCS_HOST = "docs.acme.com"
private_key = open("velu-docs-private.pem").read()

token = jwt.encode(
    {
        "host": DOCS_HOST,
        "exp": int(time.time()) + 30,
        "nonce": nonce_from_login_request,
        "expiresAt": int(time.time()) + 3600,
        "groups": ["admin"],
    },
    private_key,
    algorithm="EdDSA",
)

# Redirect to https://docs.acme.com/login/jwt-callback#{token}

import * as jose from "jose";

const DOCS_HOST = "docs.acme.com";
const signingKey = await jose.importPKCS8(process.env.VELU_DOCS_PRIVATE_KEY!, "EdDSA");

const token = await new jose.SignJWT({
  host: DOCS_HOST,
  expiresAt: Math.floor(Date.now() / 1000) + 60 * 60,
  groups: ["admin"],
  nonce: nonceFromLoginRequest,
})
  .setProtectedHeader({ alg: "EdDSA" })
  .setExpirationTime("30s")
  .sign(signingKey);

// Redirect to https://docs.acme.com/login/jwt-callback#${token}

Redirect unauthenticated readers

1. Reader opens https://docs.acme.com/quickstart.
2. Velu sends them to your login URL with redirect=%2Fquickstart and a nonce.
3. After sign-in, redirect to https://docs.acme.com/login/jwt-callback#TOKEN.
4. Velu sets the reader session cookie and returns them to /quickstart.

Make pages public

On a private site, pages require authentication by default. Mark specific pages or navigation groups as public.

Individual pages

---
title: "Getting started"
public: true
---

Groups of pages

Add "public": true on a navigation group in velu.json. Descendant pages inherit public access unless a page sets public: false.

{
  "navigation": {
    "groups": [
      {
        "group": "Get started",
        "public": true,
        "pages": ["index", "quickstart"]
      },
      {
        "group": "Internal",
        "pages": ["runbooks/deploy"]
      }
    ]
  }
}

Control access with groups

With OAuth or JWT, restrict pages to matching reader groups:

---
title: "Admin guide"
groups: ["admin", "support"]
---

Group names are case-sensitive. The reader must belong to at least one listed group. A nonempty groups list overrides public: true.

Password and workspace sessions have no groups, so they cannot open group-restricted pages.

How public pages and groups interact

• By default, private sites require authentication.
• Pages without groups are available to every authenticated reader.
• Pages with groups require a matching OAuth or JWT group.
• Pages with public: true and no groups are available to everyone.

Reader token claims

OAuth user-info responses and JWT payloads use this shape:

{
  "host": "docs.acme.com",
  "expiresAt": 1893456000,
  "groups": ["admin", "beta"]
}

For JWT, exp is when the signed token becomes invalid. Use expiresAt for how long the docs session should last after exchange.

Logout

Docs logout clears the reader session on the documentation host only. It does not sign the reader out of the Velu product.

Related topics