Skip to main content

​
Overview

By default, Geni’s docs routes (UI, JSON and MCP) return 404 outside the local environment:
config/geni.php
Outside local you have two ways to open the docs, and you can combine them:
  1. A viewApiDocs gate: decide access with your own authorization logic.
  2. Isolated docs credentials (docs_auth): a username and password that are independent of your users.

​
The viewApiDocs Gate

Define the gate in a service provider:
app/Providers/AppServiceProvider.php
With restrict_to_local enabled (the default), docs requests are handled as follows: The gate receives the authenticated user, or null for guests. User-based gates need a session, so add web to the docs middleware:
config/geni.php
Set restrict_to_local to false to skip the environment and gate check entirely and rely only on docs_auth. When both are enabled, a request must pass both.

​
Isolated Docs Credentials

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.
Set the mode to form and configure credentials in your .env file:
.env
And in config/geni.php:
config/geni.php

​
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 ends the docs session. Logging in and logging out both regenerate the session id, and logout also rotates the CSRF token.

​
HTTP Basic Authentication

If you prefer browser-native authentication without session cookies:
.env
Any request without valid Authorization: Basic ... headers will receive an HTTP 401 response with a WWW-Authenticate: Basic realm="API Documentation" header.

​
How Credentials Are Checked

  • Setting only one of the two values fails closed, so a blank value can never match a blank submission.
  • Username and password are compared in constant time (hash_equals), and both are always checked, without short-circuiting.
In 2.x a blank username or password could open the Basic Auth gate for an empty user:password. Since 3.0, make sure both values are set if you rely on the credentials gate.

​
Disabling Authentication

To remove the credentials gate (e.g. for open public developer portals), leave both username and password blank or set them to null:
.env
Outside local, the docs still follow restrict_to_local and the viewApiDocs gate. To make them fully public, define a gate that always passes or set restrict_to_local to false.