ShingleAI uses a role-based access control system to manage what team members can see and do within your organization. This guide explains the permission model and how to configure access for your team.
Role Types
Every organization member has one of three roles:
| Role | Description |
|---|
| Owner | Full access to all organization resources and settings. Can manage billing, API keys, and delete the organization. |
| Admin | Full access to business data. Can invite members and manage integrations. Cannot manage API keys or billing. |
| User | Read-only access to business data (contacts, messages, automations). Full access to their own user resources (files, preferences). Cannot access organization settings. |
Each organization must have at least one Owner. Ownership can be transferred but not removed entirely.
Permission Model
ShingleAI’s permission system is built on three core concepts:
1. Actions
Every permission check evaluates one of three actions:
| Action | HTTP Methods | Description |
|---|
read | GET | View resources |
write | POST, PUT, PATCH | Create or modify resources |
delete | DELETE | Remove resources |
2. Resources
Resources are organized hierarchically using dot notation. For example:
contacts
contacts.emails
contacts.phones
contacts.tags
3. Inheritance
Permissions flow from parent to child resources. If you grant read access to contacts, that permission automatically applies to contacts.emails, contacts.phones, and all other child resources—unless explicitly overridden.
Role Permissions
Owner Permissions
Owners have unrestricted access to all resources:
| Resource Category | Read | Write | Delete |
|---|
| Organization settings | Yes | Yes | Yes |
| Members & invites | Yes | Yes | Yes |
| API keys | Yes | Yes | Yes |
| Billing & subscription | Yes | Yes | Yes |
| All business data | Yes | Yes | Yes |
Admin Permissions
Admins have full data access with limited administrative capabilities:
| Resource Category | Read | Write | Delete |
|---|
| Organization settings | Yes | No | No |
| Members | Yes | No | No |
| Invites | Yes | Yes | Yes |
| Connections | Yes | No | No |
| Workflows | Yes | Yes | Yes |
| API keys | No | No | No |
| Billing & subscription | Yes | No | No |
| Contacts & customers | Yes | Yes | Yes |
| Messages | Yes | Yes | Yes |
| Automations | Yes | Yes | Yes |
| Files & folders | Yes | Yes | Yes |
User Permissions
Users have read-only access to organization data with full control over their own resources:
| Resource Category | Read | Write | Delete |
|---|
| Organization settings | No | No | No |
| Members | No | No | No |
| API keys | No | No | No |
| Contacts & customers | Yes | No | No |
| Messages | Yes | No | No |
| Automations | Yes | No | No |
| Own files & folders | Yes | Yes | No |
| Own user profile | Yes | Yes | No |
Resource Categories
The permission system covers these resource categories:
contacts - Contact recordscontacts.emails, contacts.phones, contacts.addresses - Contact detailscontacts.tags, contacts.notes - Organization and annotations
Customer & Business Management
customers - Customer relationshipsbusinesses - Business entitiesbusinesses.contacts, businesses.opportunities - Business associations
Communication
messages - All message typesmessages.email, messages.sms - Channel-specific messagesmessages.templates - Message templates
Organization
organization - Core organization settingsorganization.members, organization.invites - Team managementorganization.billing - Subscription and payment
Developer Resources
api_keys - API key managementmcp_keys - MCP key managementintegrations - Third-party connections
Automations
automations - Workflow automationsautomations.workflows, automations.triggers - Automation components
Files
files - File storagefolders - Folder organization
API Key Permissions
API keys support fine-grained permissions independent of user roles. When creating an API key, you can:
- Grant specific resource access (e.g., read-only contacts)
- Restrict to certain actions (e.g., read and write, no delete)
- Scope to resource hierarchies (e.g., full
messages access)
See API Key Management for details on creating and configuring API keys.
Best Practices
Principle of Least Privilege
Assign the minimum role needed for each team member:
- Use User role for team members who only need to view data
- Use Admin role for managers who need to edit data and invite members
- Reserve Owner role for account administrators
Regular Access Reviews
Periodically review your organization’s members:
- Remove inactive members promptly
- Verify role assignments match current responsibilities
- Check for any unused API keys
Separation of Duties
For sensitive operations, consider:
- Limiting Owner role to 1-2 trusted administrators
- Using separate API keys for different integrations
- Enabling audit logging to track changes
Next Steps
