> ## Documentation Index
> Fetch the complete documentation index at: https://slackhive.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings & Users

> Brand the dashboard, manage users, assign roles, import from Slack, and control per-agent access.

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

## General — platform branding

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`    |

1. Go to **Settings → General**
2. Edit any field
3. Click **Save**
4. 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.

1. Go to **Settings → Users**
2. Click **Add User**
3. Enter a username and password
4. Select a role
5. 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.

1. Go to **Settings → Users**
2. Click **Import from Slack**
3. Enter a Slack **bot token** (`xoxb-…`) with `users:read` and `users:read.email` scopes
4. 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.

<Note>
  Only active, non-bot Slack members are imported. Deactivated accounts and bots are skipped.
</Note>

## Changing a user's role

1. Go to **Settings → Users**
2. Find the user in the table (use the search box to filter by name)
3. Use the role dropdown to select a new role
4. 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:

1. Go to **Settings → Users → Import from Slack** and import your team
2. 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                   |

**Trigger** is useful when someone needs to interact with the agent in Slack (e.g. frontline staff using a bot daily) but shouldn't see agent configuration or conversation history in SlackHive.

To grant access:

1. Go to **Settings → Users**
2. Click the user row to open the side panel
3. Under **Agent Access**, find the agent
4. Select **Trigger**, **View**, or **Edit**
5. Click **Save**

To revoke access, set the level back to **None**.

<Note>
  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.
</Note>

## 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 {username} · 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.