Documentation Authentication

Protect your documentation portal and raw JSON specifications with isolated authentication.

Overview

By default, Geni routes 404 outside the local environment:

config/geni.php

'restrict_to_local' => true,

When deploying documentation to shared staging or production environments, you can disable restrict_to_local and enable isolated documentation authentication.

Documentation authentication is completely decoupled from your application’s user table, database guards, and session cookies.

Supported Modes

Geni supports two authentication modes:

1. form: A standalone HTML login page matching the docs UI theme.
2. basic: Browser-native HTTP Basic Authentication prompt.

Form-Based Authentication (Recommended)

Set the mode to form and configure credentials in your .env file:

.env

GENI_DOCS_AUTH_MODE=form
GENI_DOCS_USERNAME=internal-team
GENI_DOCS_PASSWORD=super-secret-password

And in config/geni.php:

config/geni.php

'restrict_to_local' => false,

'docs_auth' => [
    'mode' => env('GENI_DOCS_AUTH_MODE', 'form'),
    'username' => env('GENI_DOCS_USERNAME'),
    'password' => env('GENI_DOCS_PASSWORD'),
],

How Form Auth Works

• Unauthenticated visitors accessing /docs/api are redirected to /docs/api/login.
• A login screen matching the docs portal dark/light theme is presented.
• Submitting valid credentials creates an isolated session under the session key geni_docs_auth_logged_in.
• Unauthenticated requests to the JSON specification (/docs/api.json or /docs/api/v1.json) return an HTTP 401 JSON response ({"message": "Unauthorized."}), rather than an HTML redirect, preventing broken JSON parsers.
• A logout button in the sidebar footer allows users to invalidate their session.

HTTP Basic Authentication

If you prefer browser-native authentication without session cookies:

.env

GENI_DOCS_AUTH_MODE=basic
GENI_DOCS_USERNAME=admin
GENI_DOCS_PASSWORD=secret

Any request without valid Authorization: Basic ... headers will receive an HTTP 401 response with a WWW-Authenticate: Basic realm="API Documentation" header.

Disabling Authentication

To make documentation public in all environments (e.g. for open public developer portals), set username and password to null:

.env

GENI_DOCS_USERNAME=null
GENI_DOCS_PASSWORD=null