> ## Documentation Index
> Fetch the complete documentation index at: https://geni.masiting.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Documentation Authentication

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

## Overview

By default, Geni routes 404 outside the `local` environment:

```php config/geni.php theme={null}
'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 .env theme={null}
GENI_DOCS_AUTH_MODE=form
GENI_DOCS_USERNAME=internal-team
GENI_DOCS_PASSWORD=super-secret-password
```

And in `config/geni.php`:

```php config/geni.php theme={null}
'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 .env theme={null}
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 .env theme={null}
GENI_DOCS_USERNAME=null
GENI_DOCS_PASSWORD=null
```