Configure Authentication
Copy page
Set up authentication and authorization for user sign-in and team management
Configure user authentication, admin credentials, and optional OAuth providers.
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 |
Email (Optional)
| Variable | Required | Description |
|---|---|---|
RESEND_API_KEY | No | Resend API key (recommended for cloud deployments) |
SMTP_HOST | No | SMTP server hostname |
SMTP_PORT | No | SMTP server port |
SMTP_USER | No | SMTP username |
SMTP_PASSWORD | No | SMTP password |
SMTP_SECURE | No | Use TLS (default: false) |
SMTP_FROM_ADDRESS | No | From email address |
SMTP_FROM_NAME | No | From display name |
SMTP_REPLY_TO | No | Reply-to address (defaults to from address) |
Configuring Authentication
Authentication is enabled by default. Configure the required environment variables to set up your admin credentials and session security.
Sign in
Open http://localhost:3000 and sign in with the credentials you configured.
Configuring Email (Optional)
Email configuration is optional. When not configured, invitation links and password reset links are displayed in the UI for manual sharing.
When email is configured:
- Team invitations are sent via email automatically
- Users can reset their password via the Forgot password link on the login page
Option 1: Resend (Recommended for Cloud)
Add your Resend API key:
Option 2: Generic SMTP
Use any SMTP provider (Mailgun, SendGrid, self-hosted, etc.):
Local Development with Mailpit
The Docker Compose setup includes Mailpit for local email testing. Emails are captured and viewable at http://localhost:8025.
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:
For local development: http://localhost:3000/api/auth/callback/google
Troubleshooting
"Invalid credentials" on first login
Verify these environment variables are set correctly:
INKEEP_AGENTS_MANAGE_UI_USERNAME— must be a valid email formatINKEEP_AGENTS_MANAGE_UI_PASSWORD— must be at least 8 characters
Google sign-in not appearing or not working
- Ensure both
PUBLIC_GOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRETare 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)
Forgot password link not showing
The Forgot password option on the login page is only visible when email is configured. Configure SMTP or Resend to enable self-service password reset. See Configuring Email.