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.

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 user with read-only access to agents and limited organization visibility.

Capabilities:

• ✅ Chat with agents
• ✅ View agent configurations (read-only)
• ❌ Create or modify agents
• ❌ Access admin dashboard
• ❌ Manage users or settings

Use Cases:

• End users who only need to interact with agents
• Team members who don’t need configuration access

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
• ✅ View their own conversations and dashboard
• ❌ Access the Control Hub (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: in Clerk, 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 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

Permissions provide fine-grained control over specific features. You can assign permissions to any role in your Clerk Dashboard.

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.

Grant this to every role except Guest. Admin, Member, and any custom roles you create (Agent Manager, User Manager, etc.) should have this permission checked in the Clerk Dashboard. Leave it unchecked on Guest so external users can’t see your organization’s configuration.

Agent Management Permissions

Permission	Key	Description
Create Agents	org:manage_agents:create	Allows creating new agents
Update Agents	org:manage_agents:update	Allows editing and deleting agents

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	End Users (50)	Chat access only

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, see own dashboard

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 only see the chat interface and their own conversations. Your knowledge bases, skills, prompts, integrations, and other agents remain completely 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. 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://asteragents.com/api/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Agent",
    "model": "gpt-4"
  }'

# Response for users without permission:
# 403 Forbidden
# {"error": "Unauthorized: Missing org:manage_agents:create permission"}

Troubleshooting

User Can’t Create Agents

Check Role Assignment

Verify the user has either org:admin or org:agent_manager role in the Clerk Dashboard.

Verify Permissions

Ensure the role has both org:manage_agents:create and org:manage_agents:update permissions.

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 Clerk Dashboard - Verify permissions are saved correctly
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]