Roles & Permissions

Manage organization roles and permissions to control access to agents and features

Roles & Permissions

Aster Agents uses Clerk’s organization-based role and permission system to control access to features within your organization. This allows you to grant different levels of access to team members based on their responsibilities.

Overview

All users must belong to an organization to use Aster Agents. Within each organization, users are assigned roles that determine what actions they can perform. Roles can be combined with custom permissions for fine-grained access control.

Tool permissions and connections

Organization admins manage all tool controls in Control Hub → Settings → Tools & permissions: native Aster tools, provider-built-in tools, connected services, and custom MCP tools. Choose All tools, Some tools, or Blocked for a group. With Some tools, newly added tools stay disabled until allowed. Private-tool entitlements and existing user/resource permissions still apply.

Connections manages accounts, credentials, and authorization—not tool permissions. Use Connect or Manage connection from the permissions screen to open the relevant connection directly. Individual agent configurations choose a subset of the tools the organization permits. The old /control-hub/settings/integration-access address redirects to the new screen.

Slack

Built-in tools appear first, grouped by purpose, without a connection status. Expand any service to inspect its tools without changing access. Search finds individual tools across built-in capabilities, services, and discovered MCP tools.

Slack uses the same tool controls as other groups. Its expanded section also includes incoming DMs/mentions and channel access. All changes save automatically. Under Manage channels, every active channel loads at once; search by name and use Block or Unblock on that row. There is no channel-ID entry or separate save step. The Blocked filter shows current exclusions, including previously blocked channels that no longer appear in discovery.

• New Slack connections make connection-visible channels available by default. Admins can block exceptions; newly accessible channels are automatically included. Channel names are organization-visible.
• To require approval instead, set channel access to Only approved channels and use Approve on each channel Aster may use. Every other channel is excluded, even if a member invites Aster to it, and mentions there get no response. Switching back to All except blocked keeps both lists.
• Channel mentions are on by default, including existing connections without an explicit mention setting. Admins can turn them off; explicit opt-outs and channel blocks are respected. New installs request app_mentions:read; an existing installation missing that grant must reconnect.
• Blocking a channel excludes discovery, reads, sends, edits, uploads, and incoming mentions. Aster still needs channel membership before posting or reading. Slack Connect channels and group DMs remain unsupported.
• Reading history and uploading files are off by default. Enabling them may require reconnecting Slack for additional authorization. History also requires the caller’s linked Slack account and current channel membership.
• Existing and new Slack connections both use all accessible channels minus the blocklist until an admin chooses Only approved channels. Old per-channel allowlists from before October 2026 no longer restrict access; no migration action or extra save is needed. Tool capabilities and explicit blocked channels still apply.

Slack conversations

With Channel mentions and Send messages enabled, a new @Aster mention starts an Aster conversation and answers in the Slack thread. Replies in a linked thread continue the same conversation and agent. Untagged channel replies additionally require history permission and the Slack app’s message.channels / message.groups event subscriptions. An app administrator must enable those subscriptions before rollout; enabling Aster’s setting alone does not change Slack’s event configuration.

A reply to an Aster tool post can resume the conversation that produced it. Only that conversation’s owner may continue it; other people receive a private explanation and must start a new top-level mention. Posting into a channel does not share the private Aster transcript or credentials. Agents reply explicitly with Send messages, in both channels and DMs; these turns have no automatic final-answer forwarding or completion notification. Unrelated channel messages and bot messages do not start work. Threaded DMs continue their own conversation; a new top-level DM starts a new one.

Thread routing uses one shared channel_conversation relationship, scoped to the organization, provider, external account and external thread. Slack supplies the channel/thread identifiers; the shared chat handler admits and runs the user message. The first conversation linked to a thread owns that route. Credential reconnects do not erase it, but execution still requires a current linked identity and permissions. Incoming messages are deduplicated, and replies wait while the conversation is running. Existing channel blocks, tool permissions, account linking, and current membership still apply. Deleted and child/subagent conversations cannot be resumed through Slack; start a new mention instead.

Rollout requires manual approval and application of 2026-10-15-channel-conversations.sql before deploying the code. It backfills only unambiguous existing explicit channel-post links; ambiguous historical threads need a new mention. No runtime history inference or additional execution state machine is introduced.

Additional Slack tools

• Find channels searches channel names page by page within the same channel boundaries as discovery.
• Find people and Read user profiles require enabling those tools and reconnecting for users:read. They expose names, job titles and timezones—not email, phone or private custom fields. Finding a person does not grant permission to DM them.
• Add reactions and Remove Aster reactions require reactions:write. Aster cannot remove another person’s reactions.
• Read threads accepts Slack message permalinks as well as channel IDs and parent timestamps. All normal access checks still run.
• Send messages supports optional Slack formatting and returns a source link for channel posts. Proactive sends still require a user request or standing task instruction; completion alone does not authorize posting.

People and reaction capabilities are off until explicitly enabled. These controls live in the same tool list, with the same autosave behavior. Existing agents may need Sync tools to pick up updated schemas; the main Aster agent receives enabled Slack tools dynamically. Message-content search and canvas tools are not part of this release. Incoming controls remain separately configurable, but Send messages must also be enabled for Slack conversations so the agent can reply. Disabling it stops incoming DMs, mentions, and thread continuations.

Default Roles

Organization Admin (org:admin)

Full administrative access to all organization features and settings.

Capabilities:

• ✅ Create, edit, and delete agents
• ✅ Manage model providers and API keys
• ✅ Configure integrations
• ✅ Manage knowledge bases
• ✅ View organization-wide analytics
• ✅ Invite and remove users
• ✅ Assign roles and permissions
• ✅ Access all admin-only features

Use Cases:

• Organization owners
• IT administrators
• Team leads with full platform responsibility

Admin users have unrestricted access to all features, including sensitive operations like deleting agents and viewing all user activity.

Organization Member (org:member)

Standard internal user. Members can use the Control Hub and build most things, but can’t change agents.

Capabilities:

• ✅ Chat with agents and open apps
• ✅ Use the Control Hub: create and edit knowledge bases, skills, apps, and their own scheduled tasks
• ✅ Change the default agent and feedback message in General settings
• ✅ View agent configurations (read-only)
• ✅ See their own usage on the Dashboard
• ❌ Create or modify agents
• ❌ See organization-wide analytics
• ❌ Manage users, providers, the sidebar, spend caps, Aster, public app links, or secrets

Use Cases:

• Internal team members who use agents and maintain knowledge bases, skills, or apps
• For people who should only chat, use Guest

Organization Guest (org:guest)

The Guest role lets you safely invite people from outside your company into your organization so they can chat with your agents — without letting them see how those agents are built, what knowledge bases they use, or anything else in the Control Hub.

Think of it as a “customer-facing” seat. Your team builds the agent; the guest just uses it.

Capabilities:

• ✅ Chat with any agent in your organization and see their own past conversations
• ✅ Open every app in your organization (apps can’t be limited to certain people; use a separate organization for that)
• ❌ Access the Control Hub or the Dashboard (redirected back to chat on attempted navigation)
• ❌ See knowledge bases, skills, scheduled tasks, agent configurations, integrations, or organization analytics

Use Cases:

• Clients you’re delivering an agent to — they chat with it, but never see the prompts, data sources, or tools that power it
• Partners & vendors who need to interact with a specific workflow without being exposed to unrelated data in your org
• Contractors on limited engagements, where you want to revoke access in one click when the work is done
• Beta testers & pilot users evaluating an agent without being exposed to configuration they shouldn’t change

How to invite a guest: invite them to your organization and select the Guest role. They sign in and land directly on the chat — no Control Hub in their navigation, and any attempt to visit it sends them back to chat.

Access stops when you remove them. Guests are regular Clerk organization members — when you remove them from the organization, their sessions are invalidated, any API keys they created stop working, and they lose access to all conversations and data scoped to your org.

Custom Roles

Agent Manager (org:agent_manager)

This is a custom role designed for users who need to manage agents but don’t require full admin access.

Users who can create and update agents without full administrative privileges.

Capabilities:

• ✅ Create new agents
• ✅ Edit existing agents
• ✅ Delete agents
• ✅ Configure agent tools and settings
• ✅ Chat with agents
• ❌ Access organization-wide analytics
• ❌ Manage users or invitations
• ❌ Configure model providers
• ❌ Access admin-only features

Use Cases:

• AI engineers who build and maintain agents
• Product managers who configure agent behavior
• Team members responsible for specific agents

Permissions

Each role comes with its permissions already set up. You choose each person’s role; you don’t configure permissions yourself. This section explains what the permissions behind each role do.

Control Hub Access

The Control Hub is where all configuration, data, and integrations live. Granting access is a single on/off decision per role — the org:control_hub:read permission.

Permission	Key	Description
Read Control Hub	org:control_hub:read	Required to view the Control Hub and any of its resources (knowledge bases, skills, scheduled tasks, integrations, agent configuration). Users without this permission are redirected back to chat.

Every role except Guest has this permission. That’s what keeps Guests out of the Control Hub.

Agent Management Permissions

Permission	Key	Description
Create Agents	org:manage_agents:create	Allows creating new agents
Update Agents	org:manage_agents:update	Allows editing agents. Deleting an agent needs either permission

Locked agents, knowledge bases, and skills can only be changed by their author or an org admin, whatever the person’s role.

Contact your organization admin to be assigned appropriate roles based on your responsibilities.

Permission Hierarchy

Common Access Patterns

Use Case: Development Team

For a team with developers who build agents and users who only chat:

Role	Users	Access Level
Admin	Tech Lead	Full platform access
Agent Manager	AI Engineers (3)	Agent configuration only
Member	Internal Users (50)	Chat, plus knowledge bases, skills, and apps

Use Case: Agency/Consultancy

For agencies building agents for multiple clients:

Role	Users	Access Level
Admin	Account Manager	Full client setup
Agent Manager	Consultants (5)	Build & configure agents
Member	Client Team (20)	Use agents, view configs
Guest	External Stakeholders (10)	Chat only, no Control Hub

Use Case: Embedded Agents for External Users

When you onboard external parties (clients, partners) who should use your agents but not see the configuration:

Role	Users	Access Level
Admin	Internal Team	Full platform access
Guest	External Users	Chat with agents and open apps

Safely Inviting External Users

When you want to give someone outside your company access to your agents — a client, contractor, or partner — always invite them as a Guest, not a Member. This is the single most important choice for protecting your organization’s data.

Guests can't see your setup

Guests see the chat, their own conversations, and your organization’s apps. Your knowledge bases, skills, prompts, and integrations stay hidden from them.

One role per trust tier

Use Admin for internal leads, Agent Manager for internal builders, Member for internal users, and Guest for anyone outside your company.

Revoke in one click

When an engagement ends, remove the guest from your organization in Clerk. Their session is invalidated and they immediately lose access.

Review invites regularly

Check your organization’s member list monthly. Remove anyone who no longer needs access and downgrade Members to Guests if they no longer need Control Hub visibility.

Never invite external users as Members. Members can see your Control Hub, which exposes every knowledge base, skill, scheduled task, and agent configuration in your organization, and they can create and edit knowledge bases, skills, and apps. Always use Guest for anyone outside your company.

Security Best Practices

Principle of Least Privilege

Only grant the minimum permissions needed for each role. Use Agent Manager instead of Admin when full access isn’t required, and Guest instead of Member for external users.

Regular Audits

Periodically review user roles and remove access for users who no longer need it. Pay special attention to external users who’ve been around longer than their original engagement.

Separate Environments

Consider using different organizations for development, staging, and production environments.

Monitor Activity

Admins can view organization-wide analytics to monitor agent usage and user activity.

Limitations & Notes

Important Limitations:

• Permission changes may take up to 1 minute to propagate
• Users must sign out and back in to see new permissions

API Integration

If you’re using the Aster Agents API, permissions are automatically enforced:

# This request will fail without appropriate permissions
curl -X POST https://www.asteragents.com/api/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Agent",
    "model": "openai:gpt-5.5"
  }'

# Response for users without permission:
# 403 Forbidden
# {"error": "Unauthorized: Missing permission to manage agents"}

Troubleshooting

User Can’t Create Agents

Check Role Assignment

Verify the person has the Admin or Agent Manager role in your organization’s member list.

Verify Permissions

Admin and Agent Manager include both org:manage_agents:create and org:manage_agents:update. Members have neither, so a Member can’t create agents.

Session Refresh

User may need to sign out and sign back in for new permissions to take effect.

Permission Changes Not Working

1. Clear browser cache - Sometimes cached session data prevents updates
2. Check the role - Confirm the person’s role in your organization’s member list
3. Wait 1-2 minutes - Permission propagation can take time
4. Sign out/in - Force a fresh session token with new permissions

Next Steps

Build an Agent

Learn how to create and configure your first agent

Knowledge Bases

Set up knowledge bases for your agents

Security Overview

Review our security and compliance documentation

API Reference

Integrate Aster Agents into your applications

---

For questions about roles and permissions, contact support at [e-mail]