Roles and Permissions

oCore uses Role-Based Access Control (RBAC) to manage permissions across your organization. Every member is assigned a role, and each role has a set of permissions that control what the member can do. oCore provides four built-in system roles and supports creating custom roles for fine-grained access control.

Default Roles

Every organization starts with four system roles that cannot be deleted:

Owner Role

The Owner has all permissions and is the only role that can:

• Delete the organization
• Transfer ownership
• Access disaster recovery exports

Permission Model

How Permissions Work

Each permission is defined by an action and a resource:

• Action -- What operation is being performed: view or manage
• Resource -- What entity the permission applies to: servers, instances, members, etc.

The manage action always includes view -- if you can manage a resource, you can also view it.

Permission Matrix

Default Role Permissions

Owner -- All permissions (view + manage on every resource)

Admin -- All permissions except:

• Cannot delete the organization
• Cannot transfer ownership

Developer:

• view + manage: servers, instances, projects, environments, deployments, templates
• view: members, roles, org_settings, audit_logs
• No access to: agency, bulk_ops (manage), roles (manage), members (manage)

Viewer:

• view only on: servers, instances, projects, environments, deployments, members, audit_logs
• No manage permissions on any resource

Custom Roles

Create custom roles to define exactly which permissions a group of members should have.

Creating a Custom Role

curl -X POST https://ocore.example.com/api/roles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy Manager",
    "description": "Can deploy code and manage environments",
    "permissionIds": ["PERM_UUID_1", "PERM_UUID_2", "PERM_UUID_3"]
  }'

ocore role create \
  --name "Deploy Manager" \
  --description "Can deploy code and manage environments" \
  --permissions PERM_UUID_1,PERM_UUID_2,PERM_UUID_3

Listing Available Permissions

Fetch the complete list of permissions to select from when creating a custom role:

curl https://ocore.example.com/api/permissions \
  -H "Authorization: Bearer $TOKEN"

Each permission includes:

• id -- UUID for use in role creation
• action -- view or manage
• resource -- The resource name
• description -- Human-readable explanation

Updating a Custom Role

curl -X PUT https://ocore.example.com/api/roles/{roleId} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Deploy Manager",
    "description": "Updated description",
    "permissionIds": ["PERM_UUID_1", "PERM_UUID_2", "PERM_UUID_3", "PERM_UUID_4"]
  }'

Deleting a Custom Role

curl -X DELETE https://ocore.example.com/api/roles/{roleId} \
  -H "Authorization: Bearer $TOKEN"

Role Assignment

Assign roles to members during invitation or update them later:

# During invitation
curl -X POST https://ocore.example.com/api/members/invite \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "roleId": "ROLE_UUID"
  }'

# Update existing member's role
curl -X PUT https://ocore.example.com/api/members/{memberId}/role \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"roleId": "NEW_ROLE_UUID"}'

See Team Management for detailed member management instructions.

Common Custom Role Patterns

Per-Project Access

Beyond organization-level roles, oCore supports per-project access control. This allows you to restrict which members can view or manage specific projects, even if their role grants broad permissions.

Project access is checked in addition to role permissions -- a member needs both the role permission and project access to perform an action.

Required Permissions

Troubleshooting

Member cannot perform an action despite having a role

• Check the specific permissions on the member's role -- the role may lack the required permission
• If using per-project access, verify the member has access to the specific project
• Use the permissions list endpoint to verify which permissions exist
• Check the audit log for denied access events

Cannot delete a custom role

• The role may have members assigned. Reassign them first: list members with the role and update each one
• System roles (Owner, Admin, Developer, Viewer) cannot be deleted

Permissions not taking effect

• Permissions take effect on the next API request -- no session refresh needed
• Clear browser cache if the dashboard UI appears outdated
• Verify the role was saved successfully by listing roles: GET /api/roles

Too many custom roles

• Consolidate roles with similar permission sets
• Use the permission matrix above to identify overlap
• Document each role's purpose to avoid redundancy