The Settings page is visible to admins and superadmins. It is split into:
- General - branding and dashboard copy
- AI Backend - active runtime, backend credentials, Coach model, eval judge model
- Access Control - workspace-wide Slack trigger policy
- Sign in with Slack - Slack OAuth login, superadmin only
- Users - accounts, roles, imports, and per-agent access
The General tab lets superadmins rebrand the dashboard. Useful for white-labeling an internal deployment.
| Field | What it controls | Default |
|---|
| App name | Product name in the sidebar header and page titles | SlackHive |
| Tagline | One-line subtitle under the app name | AI agent teams on Slack |
| Logo URL | Replace the default logo with your own image URL | (built-in logo) |
| Dashboard title | Heading on the home page | Welcome to SlackHive |
- Go to Settings → General
- Edit any field
- Click Save
- Reload to see the new branding
Changes apply instantly for all users.
Authentication overview
SlackHive supports two login methods:
- Username / password — built-in, no external provider required
- Sign in with Slack — users log in via Slack OAuth; their Slack identity links to their SlackHive account
The superadmin account is configured via ADMIN_USERNAME / ADMIN_PASSWORD environment variables — never stored in the database. Sessions use HMAC-signed cookies; the signing key is AUTH_SECRET in your .env.
Sign in with Slack
To enable Slack OAuth login, go to Settings → Sign in with Slack and enter your Slack app’s Client ID and Client Secret (found in the Slack API console under Basic Information → App Credentials).
Once configured, users see a Sign in with Slack button on the login page.
Open vs invite-only login:
- Invite-only (default): Only users you’ve already created or imported can log in via Slack. Anyone else gets an “account not invited” error.
- Open login: Any Slack workspace member can log in and a SlackHive account is created automatically on first login.
Toggle this with the Allow any workspace member to sign in checkbox — only available once Client ID and Client Secret are saved.
Roles
SlackHive has four roles with escalating permissions:
| Role | View agents | Edit agents | Scheduled Jobs | Settings | Manage users | Activity |
|---|
| Superadmin | All | All | All jobs | ✅ | ✅ | All |
| Admin | All | All | All jobs | Most settings | ✅ | All |
| Editor | Granted only | Own + granted | Own jobs | ❌ | ❌ | Granted agents |
| Viewer | Granted only | ❌ | Granted agents (read-only) | ❌ | ❌ | ❌ |
Superadmin
Configured via ADMIN_USERNAME and ADMIN_PASSWORD in .env. This account is never stored in the database — it exists only in environment configuration. The superadmin is the only role that can access the Settings page.
Admin
Full operational access to agents, jobs, users, Activity, Observability, MCP catalog, env vars, and most Settings sections. Stored in the database and manageable via the Users page. Admins can create users, change roles, and grant per-agent access to editors and viewers. Slack sign-in settings remain superadmin-only.
Editor
Agents are hidden by default. Editors only see:
- Agents they created themselves (full edit access automatically)
- Agents an admin explicitly granted them View or Edit access to
Editors can create and manage scheduled jobs for agents they have edit access to. They can add env vars and edit or delete ones they added themselves.
Viewer
Agents are hidden by default. Viewers only see agents an admin has explicitly granted them (View access only).
On a granted agent, viewers can browse read-only content such as Overview, Instructions, Tools, Wiki, Audiences, and Settings but cannot make changes. The Test, Export, Download wiki, Logs, and History controls are hidden.
Viewers can see the Scheduled Jobs page in read-only mode — they see jobs for the agents they have access to, but cannot create, edit, or delete jobs.
Creating users
Only superadmins and admins can create users.
- Go to Settings → Users
- Click Add User
- Enter a username and password
- Select a role
- Click Create
Users can log in immediately at the /login page.
Importing from Slack
If your team is already on Slack, you can bulk-import workspace members so they can sign in via Slack without self-registering.
- Go to Settings → Users
- Click Import from Slack
- Enter a Slack bot token (
xoxb-…) with users:read and users:read.email scopes
- Click Import
SlackHive fetches your workspace’s active members and creates accounts for anyone not already in the system. Existing users are matched by email and their Slack identity is linked — they can then use Sign in with Slack.
Imported users start with the viewer role and no agent access — assign roles and grants after importing.
Only active, non-bot Slack members are imported. Deactivated accounts and bots are skipped.
Changing a user’s role
- Go to Settings → Users
- Find the user in the table (use the search box to filter by name)
- Use the role dropdown to select a new role
- Changes take effect on the user’s next page load
Open to Workspace
By default, any Slack workspace member can trigger agents — no user import or access grant needed. This is the easiest way to get started.
To restrict access to specific users, turn off Open to Workspace in Settings → Access Control. Once restricted:
- Go to Settings → Users → Import from Slack and import your team
- Grant each user a Trigger, View, or Edit access level on the agents they should be able to use
Users who message the bot without access will receive a clear explanation:
- Not imported into SlackHive: “You don’t have access to this agent. Ask an admin to grant you access in SlackHive — you’ll need to be added as a user first.”
- Imported but not granted: “You don’t have access to this agent. Ask an admin to grant you Trigger (or higher) access to it in SlackHive.”
| Setting | Who can trigger agents |
|---|
| On (default) | Any Slack workspace member |
| Off | Only imported users with a Trigger, View, or Edit grant |
Per-agent access grants
Agents are invisible to editors and viewers until an admin grants access. There are three access levels:
| Level | SlackHive dashboard | Slack bot |
|---|
| Trigger | Hidden | Bot responds to their messages |
| View | Read-only | Bot responds |
| Edit | Full edit access | Bot responds |
- Go to Settings → Users
- Click the user row to open the side panel
- Under Agent Access, find the agent
- Select Trigger, View, or Edit
- Click Save
To revoke access, set the level back to None.
Editors automatically have Edit access on agents they created — no grant needed. Admins and superadmins always see all agents and the bot always responds to them regardless of grants.
Env Vars ownership
The Settings → Env Vars secret store tracks who added each secret:
- Admins / superadmins — create, edit, and delete any env var
- Editors — create env vars; can only edit or delete ones they added themselves
- Viewers — no access
Each row shows Added by · date so admins can audit ownership and rotation history.
Permissions enforcement
All permissions are enforced server-side — not just hidden in the UI. A viewer who manually calls an API endpoint to edit an agent will receive a 403 response.
Key rules:
GET /api/agents is filtered — editors and viewers only receive agents they have access to- Individual agent routes return 404 (not 403) for agents a user has no access to, avoiding leaking agent existence
- Write operations on an agent require: admin, superadmin, or editor with ownership / Edit grant
- Settings mutations require superadmin
- User management requires admin or superadmin
- Jobs are filtered by accessible agents — each user only sees jobs for agents they can access
- Slack bot access is also enforced — users with no access level (or None) receive no response from the bot
Session behavior
Sessions use HMAC-signed cookies with no expiry by default. Sessions are invalidated when:
- The user logs out explicitly
AUTH_SECRET is rotated in .env (invalidates all sessions immediately)
Sessions are stateless HMAC tokens — there is no session table and no way to invalidate individual sessions without rotating the secret. 
