Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jonwiggins/optio/llms.txt

Use this file to discover all available pages before exploring further.

Optio authenticates users through OAuth. When a user visits the web UI, they are redirected to an OAuth provider to log in. After a successful login, Optio creates a session that lasts 30 days. At least one OAuth provider must be configured before anyone can log in. The setup wizard walks through this on first install.

​
How providers are enabled

A provider becomes available on the login page as soon as both its client ID and client secret are set. You can enable multiple providers simultaneously — users can choose between them at login. Set credentials via Helm values or directly as environment variables:
values.yaml
auth:
  github:
    clientId: "Ov23li..."
    clientSecret: "your-secret"
  google:
    clientId: "123456789-abc.apps.googleusercontent.com"
    clientSecret: "your-secret"
  gitlab:
    clientId: "your-client-id"
    clientSecret: "your-secret"
    # baseUrl: https://gitlab.yourcompany.com  # self-hosted only

​
GitHub

Required scopes: read:user, user:email
1

Create a GitHub OAuth App

Go to github.com/settings/developers and click New OAuth App.
2

Configure the app

Set Authorization callback URL to:
https://<your-api-host>/api/auth/github/callback
Replace <your-api-host> with the value of API_PUBLIC_URL.
3

Copy credentials into Helm values

values.yaml
auth:
  github:
    clientId: "Ov23li..."
    clientSecret: "your-secret"

​
Google

Required scopes: openid, email, profile
1

Create an OAuth 2.0 client

Open the Google Cloud Console and navigate to APIs & Services > Credentials > Create Credentials > OAuth client ID. Choose Web application.
2

Add the redirect URI

Under Authorized redirect URIs, add:
https://<your-api-host>/api/auth/google/callback
3

Copy credentials into Helm values

values.yaml
auth:
  google:
    clientId: "123456789-abc.apps.googleusercontent.com"
    clientSecret: "your-secret"

​
GitLab

Required scopes: read_user Optio supports both GitLab.com and self-hosted GitLab instances.
1

Create a GitLab application

Go to your GitLab instance under User Settings > Applications and create a new application.
2

Add the redirect URI

Set the redirect URI to:
https://<your-api-host>/api/auth/gitlab/callback
3

Copy credentials into Helm values

values.yaml
auth:
  gitlab:
    clientId: "your-client-id"
    clientSecret: "your-secret"
For a self-hosted GitLab instance, also set baseUrl:
values.yaml
auth:
  gitlab:
    clientId: "your-client-id"
    clientSecret: "your-secret"
    baseUrl: "https://gitlab.yourcompany.com"

​
Sessions

After a successful OAuth login, Optio sets an optio_session cookie in the user’s browser. Sessions are valid for 30 days. Cookies are HttpOnly and SameSite=Lax. Users can log out at any time from the user menu, which revokes the session immediately.

​
Local development bypass

The auth bypass must never be used in production. Enabling it removes all access control — any user with network access to the deployment can use Optio without logging in.
For local development, you can disable authentication entirely so you don’t need to configure OAuth providers:
values.yaml
auth:
  disabled: true
Or via environment variable: 
OPTIO_AUTH_DISABLED=true
When disabled, the web UI and API accept all requests without a session, and the user profile shows as “Local Dev”.

Build docs developers (and LLMs) love

Get started for freeTalk to us