Skip to content

Authentication

AgentCrew includes a built-in authentication system with user management, organizations, invite-based onboarding, and role-based access control. Authentication is configured via the AUTH_PROVIDER environment variable and supports two modes: local (default) and noop.

Authentication Modes

Local Authentication (default)

Set AUTH_PROVIDER=local to enable email/password authentication with JWT tokens. This is the default mode when using the installer.

  • Users register with email, password, name, and organization name.
  • Passwords are hashed with bcrypt (cost factor 12).
  • JWT access tokens (default 24h) and refresh tokens (default 7d) are issued on login.
  • Tokens are signed with HMAC-SHA256 using the JWT_SECRET environment variable.
  • The frontend automatically refreshes expired access tokens using the refresh token.

Required environment variables for local mode:

Variable Description
JWT_SECRET Secret for signing JWT tokens. Minimum 32 characters. Generate with openssl rand -base64 48.
SETTINGS_ENCRYPTION_KEY Key for encrypting sensitive data (API keys, invite tokens) at rest using AES-256-GCM. Generate with openssl rand -base64 32.

Noop Authentication (no auth)

Set AUTH_PROVIDER=noop to disable authentication entirely. In this mode:

  • No login screen is shown.
  • A default organization and user are created automatically.
  • All API requests are accepted without tokens.
  • Ideal for local development, testing, or single-user self-hosted setups where security is handled at the network level.
Note: Switching from noop to local is seamless. Existing data (teams, agents, settings) is automatically associated with the default organization. You will just need to create your first user account.

Organizations

Every user belongs to an organization. Organizations provide data isolation: teams, agents, schedules, webhooks, settings, and all other resources are scoped to the organization. Users in one organization cannot see or access resources from another.

Single-Tenant Mode (default)

With MULTI_TENANT=false (the default), only one organization can exist. The first user who registers creates the organization and becomes its admin. Additional users can only join via invite.

Multi-Tenant Mode

With MULTI_TENANT=true, anyone can register and create a new organization. Each organization is fully isolated with its own users, teams, settings, and data.

User Roles

AgentCrew uses a simple two-role model:

Role Capabilities
Admin Full access. Can manage organization settings, invite users, change roles, reset passwords, and remove members. The first user (organization creator) is always an admin and cannot be downgraded.
Member Can create and manage teams, agents, schedules, webhooks, and settings. Cannot manage users or organization settings.
Safety: The system enforces that at least one admin always exists. The organization owner cannot be removed or downgraded.

First-Time Setup

  1. Install AgentCrew using the Quick Start guide. The installer generates all required secrets automatically.
  2. Open the UI at http://localhost:8080. You will see the registration page.
  3. Create your account with your name, email, password, and organization name. This account becomes the organization admin.
  4. Add API keys in Settings to start deploying agent teams.

Inviting Users

Admins can invite new users from the Organization Settings page:

  1. Go to Organization Settings in the sidebar.
  2. In the Invitations section, enter the email address and click Invite.
  3. Copy the invite link from the listing and share it with the user.
  4. The invited user opens the link, fills in their name and password, and joins the organization.

Invitations expire after 7 days. Admins can cancel pending invitations at any time. The system prevents duplicate invites: you cannot invite an email that is already a member or has a pending invitation.

Password Management

Changing Your Password

Users can change their own password from their Profile page. They must enter their current password and the new one. Passwords must be at least 8 characters and include an uppercase letter, a lowercase letter, and a digit.

Admin Password Reset

Admins can reset any member's password from the Organization Settings page. When reset, a temporary password is generated and displayed. The user must change it on their next login (a forced password change screen is shown).

WebSocket Authentication

Real-time chat connections use WebSocket. Since WebSocket does not support custom headers, the JWT token is passed as a query parameter: 

ws://localhost:8080/api/ws/team/<team-id>?token=<jwt-access-token>

The API server validates the token before upgrading the connection. In noop mode, no token is required.

Security Details

  • Password hashing: bcrypt with cost factor 12.
  • JWT signing: HMAC-SHA256. The none algorithm is explicitly blocked.
  • Token types: Access and refresh tokens include a type claim to prevent cross-use.
  • Invite tokens: 32 bytes from crypto/rand. A SHA-256 hash is stored in the database; the raw token is encrypted with AES-256-GCM for admin retrieval.
  • Sensitive data at rest: API keys and settings values are encrypted with AES-256-GCM using SETTINGS_ENCRYPTION_KEY.
  • Email normalization: All emails are lowercased and trimmed to prevent case-sensitivity issues.
  • Data isolation: All database queries are scoped to the user's organization ID, enforced at the middleware level.

Disabling Authentication

To run AgentCrew without authentication (useful for local development or trusted networks): 

# In your .env file
AUTH_PROVIDER=noop

In noop mode, JWT_SECRET and SETTINGS_ENCRYPTION_KEY are not required. All API endpoints accept unauthenticated requests, and a default user and organization are created automatically.

Next Steps

  • Configuration: Full list of environment variables including auth settings.
  • Architecture: How the auth layer integrates with the API server and frontend.
  • Quick Start: Get AgentCrew running with authentication in one command.