Configure Authentication

Configure user authentication, admin credentials, and optional OAuth providers.

Note

For a feature overview of authentication and authorization, see Access Control.

Architecture

The framework uses two components for access control:

Component	Purpose
Better Auth	User authentication, sessions, and OAuth providers
SpiceDB	Fine-grained authorization and permission checks

Better Auth handles user sign-in and supports many authentication plugins including GitHub, Microsoft, SAML, passkeys, and more. See the Better Auth documentation to add additional sign-in methods.

SpiceDB manages organization and project-level permissions using a relationship-based access control model.

Prerequisites

Docker Compose environment running (see Local Development)
At least one AI provider API key configured

Environment Variables Reference

Authentication

Variable	Required	Description
`BETTER_AUTH_SECRET`	Yes	Secret for session encryption (32+ chars)
`INKEEP_AGENTS_MANAGE_UI_USERNAME`	Yes	Initial admin email address
`INKEEP_AGENTS_MANAGE_UI_PASSWORD`	Yes	Initial admin password (8+ chars)

Authorization

Variable	Required	Description
`SPICEDB_ENDPOINT`	Yes	SpiceDB gRPC endpoint (default: `localhost:50051`)
`SPICEDB_PRESHARED_KEY`	Yes	SpiceDB preshared key for authentication

OAuth Providers (Optional)

Variable	Required	Description
`PUBLIC_GOOGLE_CLIENT_ID`	No	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	No	Google OAuth client secret

Configuring Authentication

Authentication is enabled by default. Configure the required environment variables to set up your admin credentials and session security.

Generate a secret

Create a secure secret for session encryption:

openssl rand -base64 32

Configure environment variables

Add these to your .env file:

.env

# Authentication secret (paste your generated secret)
BETTER_AUTH_SECRET=<your-generated-secret>

# Initial admin credentials
INKEEP_AGENTS_MANAGE_UI_USERNAME=admin@example.com
INKEEP_AGENTS_MANAGE_UI_PASSWORD=<secure-password-8-chars-min>

# Authorization (SpiceDB)
SPICEDB_ENDPOINT=localhost:50051
SPICEDB_PRESHARED_KEY=dev-secret-key

Restart services

docker compose up -d

Open http://localhost:3000 and sign in with the credentials you configured.

Adding OAuth Providers

Google OAuth

Create OAuth application

Go to the Google Cloud Console
Navigate to APIs & Services → Credentials
Click Create Credentials → OAuth client ID
Select Web application

Configure redirect URI

Add this authorized redirect URI:

{your-app-url}/api/auth/callback/google

For local development: http://localhost:3000/api/auth/callback/google

Add credentials to environment

.env

PUBLIC_GOOGLE_CLIENT_ID=<your-client-id>
GOOGLE_CLIENT_SECRET=<your-client-secret>

Restart services

docker compose up -d

The Google sign-in option will now appear on the login page.

Troubleshooting

Verify these environment variables are set correctly:

INKEEP_AGENTS_MANAGE_UI_USERNAME — must be a valid email format
INKEEP_AGENTS_MANAGE_UI_PASSWORD — must be at least 8 characters

Ensure both PUBLIC_GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set
Verify the redirect URI in Google Cloud Console matches your app URL exactly

Users can't see projects

Organization Members need explicit project-level roles to access projects. Either:

Assign them a project role via Project Settings → Members
Promote them to organization Admin (gives access to all projects)

On this page