Skip to main content
When you deploy your Geni documentation portal to a shared staging or production environment, you probably do not want it publicly accessible to everyone. Geni ships with built-in portal authentication that is completely decoupled from your application’s user table, database guards, and session cookies — there is no need to create app users or configure Sanctum. You set a single username and password in your environment file, and Geni handles the rest behind its own isolated session key.
By default, Geni routes return a 404 response outside the local environment, controlled by 'restrict_to_local' => true in config/geni.php. You must set this to false before portal authentication takes effect in staging or production.

​
Supported Modes

Geni supports two authentication modes for the docs portal:
  1. form — A standalone HTML login page that matches the docs portal dark/light theme.
  2. basic — Browser-native HTTP Basic Authentication via a WWW-Authenticate challenge header.

​
Form-Based Authentication

Form authentication is the recommended mode. It presents a themed login screen, stores an authenticated session under an isolated key, and handles unauthenticated API spec requests gracefully so JSON parsers never receive an unexpected HTML redirect. Set your credentials in .env:
.env
Then reference those values in config/geni.php:
config/geni.php
Here is how the form login flow works end to end:
1

Redirect to login

Unauthenticated visitors accessing /docs/api are redirected to /docs/api/login, where a themed login form is rendered.
2

Validate credentials

On form submission, Geni checks the provided username and password against the configured values.
3

Create isolated session

Valid credentials create a session entry under the key geni_docs_auth_logged_in — separate from any existing application session.
4

JSON spec protection

Unauthenticated requests to the raw JSON spec (e.g. /docs/api.json, /docs/api/v1.json) return an HTTP 401 JSON response ({"message": "Unauthorized."}) rather than an HTML redirect, preventing broken JSON parsers.
5

Sign out

A logout button in the sidebar footer lets authenticated users invalidate their session at any time.

​
HTTP Basic Authentication

If you prefer browser-native authentication without session cookies, use the basic mode. Any request without a valid Authorization: Basic … header receives an HTTP 401 response with a WWW-Authenticate: Basic realm="API Documentation" header, triggering the browser’s built-in credentials dialog.
.env

​
Disabling Authentication

To make the documentation portal fully public — for example, when building an open developer portal — set both credentials to null:
.env
With null credentials, Geni serves the portal and all spec endpoints without any authentication check, regardless of the configured mode.
If you disable restrict_to_local without configuring authentication credentials, your OpenAPI specifications and documentation portal become publicly accessible. Only do this intentionally for public-facing developer portals.