Helix Documentation
Private Deployment
Authentication and Authorization

Authentication and Authorization

Authentication

Helix includes built-in multi-tenant authentication. You can also integrate with a custom OIDC provider if you have an existing identity management system.

Built-in Authentication

Helix’s built-in authentication system handles user registration, login, and session management. No additional configuration is required for basic deployments.

Custom OIDC Provider

Helix supports OpenID Connect (OIDC) for integration with external identity providers like Okta, Auth0, Azure AD, or Google.

Configuration

Configure your OIDC provider using these environment variables:

VariableDescriptionDefault
OIDC_ENABLEDEnable custom OIDC authenticationfalse
OIDC_URLURL of your OIDC provider-
OIDC_CLIENT_IDClient ID for your applicationapi
OIDC_CLIENT_SECRETClient secret for your application-
OIDC_AUDIENCEExpected audience claim in JWT (optional)-
OIDC_SCOPESRequested OIDC scopes, comma-separatedopenid,profile,email
OIDC_SECURE_COOKIESUse secure cookies for sessionstrue

Provider Requirements

Your OIDC provider must support:

  1. Standard OIDC authorization code flow
  2. The scopes specified in OIDC_SCOPES (default: openid, profile, email)
  3. JSON Web Token (JWT) issuance
  4. Redirect URI: ${HELIX_URL}/api/v1/auth/callback

Authorization

Administrators

Configure administrator access using the ADMIN_USER_IDS environment variable:

ADMIN_USER_IDS=user1,user2,user3

Use all to grant admin access to all authenticated users:

ADMIN_USER_IDS=all

Organizations and Teams

Helix provides hierarchical access control:

  • Organizations are top-level entities
  • Teams belong to organizations
  • Users join organizations with owner or member roles
  • Access grants control resource permissions

Member Management 

# Add member to organization
helix member add --organization <org-name> --user-email <email> --role <role>

# List organization members
helix member list --organization <org-name>

# Remove member
helix member remove --organization <org-name> --user-email <email>

Organization roles:

  • owner: Full administrative access
  • member: Can view members/teams, create agents

Team Management 

# Add member to team
helix member add --organization <org-name> --team <team-name> --user-email <email>

# List team members
helix member list --organization <org-name> --team <team-name>

# Remove from team
helix member remove --organization <org-name> --team <team-name> --user-email <email>

Access Grants

Share agents and knowledge with users or teams:

# Grant access
helix app grant-access <app-id> --user <user-email> --roles read,write
helix app grant-access <app-id> --team <team-id> --roles read,write

# List access grants
helix app list-access-grants <app-id>

# Remove access
helix app remove-access <app-id> <access-grant-id>

Best Practices

  1. Role Assignment: Assign owner roles sparingly; use team memberships for fine-grained control
  2. Team Structure: Create teams based on projects or functional groups
  3. Access Management: Grant minimum required access; prefer team-based grants over individual grants
  4. Auditing: Regularly review access grants and memberships
Last updated on
Environment VariablesVision RAG with Haystack and VLLM