Skip to main content

​
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

​
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.

​
Agent Management Permissions

PermissionKeyDescription
Create Agentsorg:manage_agents:createAllows creating new agents
Update Agentsorg:manage_agents:updateAllows editing and deleting agents
Both permissions are required for the Agent Manager role. Assign them in your Clerk Dashboard.

​
Setting Up Roles & Permissions

​
Step 1: Configure in Clerk Dashboard

  1. Navigate to your Clerk Dashboard
  2. Go to Organizations → Roles & Permissions
  3. Create a new role or edit an existing one

​
Step 2: Create Agent Manager Role

1

Create the Role

  1. Click Add role
  2. Name: Agent Manager
  3. Key: agent_manager (final key will be org:agent_manager)
  4. Description: Can create and update agents but is not an admin
2

Add Permissions

Under Custom permissions, create a new feature called manage_agents, then add:
  • Permission: create (key: org:manage_agents:create)
  • Permission: update (key: org:manage_agents:update)
3

Assign to Users

Go to Organizations in the Clerk Dashboard, select your organization, and assign the Agent Manager role to users

​
Step 3: Verify Access

Users with the Agent Manager role should now be able to:
  • Access the Control Hub → Agents page
  • Create new agents
  • Edit and delete existing agents
  • But NOT access admin-only features like user management or organization analytics

​
Permission Hierarchy

​
Common Access Patterns

​
Use Case: Development Team

For a team with developers who build agents and users who only chat:
RoleUsersAccess Level
AdminTech LeadFull platform access
Agent ManagerAI Engineers (3)Agent configuration only
MemberEnd Users (50)Chat access only

​
Use Case: Agency/Consultancy

For agencies building agents for multiple clients:
RoleUsersAccess Level
AdminAccount ManagerFull client setup
Agent ManagerConsultants (5)Build & configure agents
MemberClient Team (20)Use agents, view configs

​
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.

Regular Audits

Periodically review user roles and remove access for users who no longer need it.

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:
  • Maximum 10 custom roles per organization (contact support if you need more)
  • Permission changes may take up to 1 minute to propagate
  • Users must sign out and back in to see new permissions
System Permissions vs Custom Permissions:
  • Clerk’s system permissions (like org:sys_profile:manage) power Clerk’s UI components
  • These are NOT included in API session claims
  • Use custom permissions (like org:manage_agents:create) for API authorization

​
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

Verify the user has either org:admin or org:agent_manager role in the Clerk Dashboard.
Ensure the role has both org:manage_agents:create and org:manage_agents:update permissions.
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 patrick@asteragents.com