Organizations and Permissions

Organizations are the foundation of access control and resource management in Beacon Tower. This guide covers how to structure organizations, manage users and groups, and implement fine-grained permissions.

Understanding Tenants and Organizations

Tenants

Tenants are the top-level isolation boundary in Beacon Tower. Each tenant is completely isolated from others and has its own set of organizations, users, and resources.

# Get all tenants (requires tenant-level permissions)
curl -X GET "https://api.beacontower.ai/tenants" \
  -H "X-API-Key: your-api-key"

# Get specific tenant
curl -X GET "https://api.beacontower.ai/tenants/{tenantId}" \
  -H "X-API-Key: your-api-key"

Each tenant has:

id — Unique identifier
displayName — Human-readable name
permissions — Tenant-level permissions configuration

Organizations

Organizations provide hierarchical structure within a tenant. They control:

Access control — Who can access which resources
Resource ownership — Which organization owns assets and other entities
Permission inheritance — Child organizations inherit permission limits from parents

Key properties:

id — Unique identifier
displayName — Organization name
parentOrganizationId — Parent organization (null for root organizations)
privileges — List of enabled privileges (e.g., asset_management, user_management)
contacts — Contact information for the organization

Organization Hierarchy

Organizations form a tree structure within a tenant. Here's a typical enterprise setup:

Your Organization (Root)
├── Customer A
│   └── Asset 1
├── Customer B
├── Reseller
│   ├── Customer C
│   │   └── Asset 2
│   └── Customer D
│       └── Asset 3
└── Service Partner
    └── Asset 1, Asset 2 (shared)

Important: Resource access is NOT restricted by hierarchy. Assets can be shared with any organization regardless of their position in the tree. The hierarchy primarily determines privilege inheritance and organizational structure.

Creating Organizations

# Create a root organization
curl -X POST "https://api.beacontower.ai/organizations" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Acme Corporation",
    "parentOrganizationId": null,
    "privileges": [
      "asset_management",
      "user_management",
      "dashboard_management",
      "alarm_management"
    ],
    "contacts": {
      "email": "admin@acme.com",
      "phone": "+1-555-0100"
    }
  }'

# Create a child organization
curl -X POST "https://api.beacontower.ai/organizations" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Customer A",
    "parentOrganizationId": "{parent-org-id}",
    "privileges": ["asset_management", "dashboard_management"]
  }'

Managing Organizations

# Get all organizations
curl -X GET "https://api.beacontower.ai/organizations" \
  -H "X-API-Key: your-api-key"

# Get specific organization
curl -X GET "https://api.beacontower.ai/organizations/{organizationId}" \
  -H "X-API-Key: your-api-key"

# Update organization
curl -X PATCH "https://api.beacontower.ai/organizations/{organizationId}" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Updated Name",
    "privileges": ["asset_management", "user_management", "alarm_management"]
  }'

# Delete organization
curl -X DELETE "https://api.beacontower.ai/organizations/{organizationId}" \
  -H "X-API-Key: your-api-key"

Organization Settings

Each organization has configurable settings:

# Get organization settings
curl -X GET "https://api.beacontower.ai/organizations/{organizationId}/settings" \
  -H "X-API-Key: your-api-key"

# Update organization settings
curl -X PUT "https://api.beacontower.ai/organizations/{organizationId}/settings" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "America/New_York",
    "defaultDashboard": "{dashboard-id}",
    "notificationPreferences": {
      "emailEnabled": true,
      "smsEnabled": false
    }
  }'

Users and Groups

Users

Users are individual accounts within your tenant. Each user belongs to one or more organizations through relations.

# Create a user
curl -X POST "https://api.beacontower.ai/users" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Jane Doe",
    "email": "jane.doe@acme.com",
    "phoneNumber": "+1-555-0123"
  }'

# Get all users
curl -X GET "https://api.beacontower.ai/users" \
  -H "X-API-Key: your-api-key"

# Get specific user
curl -X GET "https://api.beacontower.ai/users/{userId}" \
  -H "X-API-Key: your-api-key"

# Update user
curl -X PATCH "https://api.beacontower.ai/users/{userId}" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Jane Smith",
    "phoneNumber": "+1-555-0199"
  }'

# Delete user
curl -X DELETE "https://api.beacontower.ai/users/{userId}" \
  -H "X-API-Key: your-api-key"

User Settings

# Get user settings
curl -X GET "https://api.beacontower.ai/users/{userId}/settings" \
  -H "X-API-Key: your-api-key"

# Update user settings
curl -X PUT "https://api.beacontower.ai/users/{userId}/settings" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "en",
    "theme": "dark",
    "emailNotifications": true
  }'

Groups

Groups are collections of users that simplify permission management and notification routing. Instead of assigning permissions to individual users, you can assign them to groups.

# Create a group
curl -X POST "https://api.beacontower.ai/groups" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Operations Team",
    "description": "Day-to-day operations staff"
  }'

# Get all groups
curl -X GET "https://api.beacontower.ai/groups" \
  -H "X-API-Key: your-api-key"

# Get specific group
curl -X GET "https://api.beacontower.ai/groups/{groupId}" \
  -H "X-API-Key: your-api-key"

# Update group
curl -X PATCH "https://api.beacontower.ai/groups/{groupId}" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Operations & Maintenance",
    "description": "Expanded team responsibilities"
  }'

# Delete group
curl -X DELETE "https://api.beacontower.ai/groups/{groupId}" \
  -H "X-API-Key: your-api-key"

Roles and Privileges

Privileges determine what members of an organization can do. They are organization-level capabilities that must be explicitly granted.

Available Privileges

asset_management — Create, update, and manage assets
dashboard_management — Create and edit dashboards
user_management — Manage users within the organization
tree_management — Manage organization hierarchy
model_management — Define and manage asset models
alarm_management — Configure and manage alarms
organization_management — Manage organization settings
provider_management — Manage integration providers
provider_client_management — Manage provider clients
notification_management — Configure notification rules
firmware_management — Manage firmware updates

Privilege Hierarchy

Organization privilege is the primary level — it determines what operations are available within that organization.

User privilege is secondary — individual users can be granted or restricted from specific privileges, but they cannot exceed the organization's privilege set.

New organizations start with no privileges. You must explicitly grant privileges when creating an organization. Child organizations can only have privileges that their parent organization also has.

Checking Privileges

# Check if a subject has a specific privilege
curl -X POST "https://api.beacontower.ai/privileges/check" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectType": "user",
    "subjectId": "{user-id}",
    "organizationId": "{organization-id}",
    "privilege": "asset_management"
  }'

Response:

{
  "hasPrivilege": true
}

Auth Relations

Relations connect subjects (users, groups, organizations, tenants) to resources (assets, dashboards, etc.) with specific access levels.

Relation Types

owner — Full control, including delete and share permissions
manager — Can edit and configure, but cannot delete
member — Standard access (organizations only)
viewer — Read-only access

Access Levels

Each relation type grants different access levels:

Relation Type	View	Manage	Delete	Share
`owner`	✓	✓	✓	✓
`manager`	✓	✓	✗	✗
`viewer`	✓	Limited*	✗	✗
`member`	✓	Org-dependent	Org-dependent	Org-dependent

Note: Viewers can read resources and set writable properties on assets (e.g., updating sensor values), but cannot modify configuration or metadata.

Creating Relations

# Give a user access to an organization (make them a member)
curl -X POST "https://api.beacontower.ai/relations" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectType": "user",
    "subjectId": "{user-id}",
    "resourceType": "organization",
    "resourceId": "{organization-id}",
    "relation": "member"
  }'

# Give an organization access to an asset
curl -X POST "https://api.beacontower.ai/relations" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectType": "organization",
    "subjectId": "{organization-id}",
    "resourceType": "asset",
    "resourceId": "{asset-id}",
    "relation": "manager"
  }'

# Give a group viewer access to a dashboard
curl -X POST "https://api.beacontower.ai/relations" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectType": "group",
    "subjectId": "{group-id}",
    "resourceType": "dashboard",
    "resourceId": "{dashboard-id}",
    "relation": "viewer"
  }'

Finding Relations

# Find all relations for a subject
curl -X POST "https://api.beacontower.ai/relations/find" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectType": "user",
    "subjectId": "{user-id}"
  }'

# Find who has access to a resource
curl -X POST "https://api.beacontower.ai/relations/find" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType": "asset",
    "resourceId": "{asset-id}"
  }'

# Find specific relation type
curl -X POST "https://api.beacontower.ai/relations/find" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectType": "organization",
    "resourceType": "asset",
    "relation": "owner"
  }'

Deleting Relations

# Remove a user from an organization
curl -X DELETE "https://api.beacontower.ai/relations/user/{userId}/organization/{organizationId}/member" \
  -H "X-API-Key: your-api-key"

# Remove organization access to an asset
curl -X DELETE "https://api.beacontower.ai/relations/organization/{organizationId}/asset/{assetId}/manager" \
  -H "X-API-Key: your-api-key"

Permissions in Practice

How Access Works

Most resource access in Beacon Tower follows this pattern:

Organization gets access — Create a relation between an organization and a resource (asset, dashboard, etc.)
Users inherit access — Users who are members of that organization automatically gain access to the resource
Access level determines capabilities — The relation type (owner, manager, viewer) determines what operations are allowed

Example workflow:

# Step 1: Create an organization
ORG_ID=$(curl -X POST "https://api.beacontower.ai/organizations" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Service Team", "privileges": ["asset_management"]}' \
  | jq -r '.id')

# Step 2: Add a user to the organization
curl -X POST "https://api.beacontower.ai/relations" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d "{
    \"subjectType\": \"user\",
    \"subjectId\": \"{user-id}\",
    \"resourceType\": \"organization\",
    \"resourceId\": \"$ORG_ID\",
    \"relation\": \"member\"
  }"

# Step 3: Give the organization access to an asset
curl -X POST "https://api.beacontower.ai/relations" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d "{
    \"subjectType\": \"organization\",
    \"subjectId\": \"$ORG_ID\",
    \"resourceType\": \"asset\",
    \"resourceId\": \"{asset-id}\",
    \"relation\": \"manager\"
  }"

# Step 4: Verify the user can now manage the asset
curl -X POST "https://api.beacontower.ai/permissions/check" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectType": "user",
    "subjectId": "{user-id}",
    "resourceType": "asset",
    "resourceId": "{asset-id}",
    "permission": "manage"
  }'

Permission Checks

While relations define the access structure, permissions are the runtime checks that determine if a specific operation is allowed.

Check Permission

# Check if a user can perform an action on a resource
curl -X POST "https://api.beacontower.ai/permissions/check" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectType": "user",
    "subjectId": "{user-id}",
    "resourceType": "asset",
    "resourceId": "{asset-id}",
    "permission": "manage"
  }'

Response:

{
  "allowed": true
}

Available permissions: view, manage, delete, share

Lookup Resources

Find all resources a subject can access:

# Find all assets a user can view
curl -X POST "https://api.beacontower.ai/permissions/lookup-resources" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectType": "user",
    "subjectId": "{user-id}",
    "resourceType": "asset",
    "permission": "view"
  }'

Response:

{
  "resourceIds": [
    "{asset-id-1}",
    "{asset-id-2}",
    "{asset-id-3}"
  ]
}

Lookup Subjects

Find all subjects that have access to a resource:

# Find all users who can manage a specific asset
curl -X POST "https://api.beacontower.ai/permissions/lookup-subjects" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectType": "user",
    "resourceType": "asset",
    "resourceId": "{asset-id}",
    "permission": "manage"
  }'

Response:

{
  "subjectIds": [
    "{user-id-1}",
    "{user-id-2}"
  ]
}

Different Access Levels for Different Users

To give different users different access levels to the same resource, use separate organizations:

# Create viewer organization
VIEWER_ORG=$(curl -X POST "https://api.beacontower.ai/organizations" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Viewers", "privileges": []}' \
  | jq -r '.id')

# Create manager organization
MANAGER_ORG=$(curl -X POST "https://api.beacontower.ai/organizations" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Managers", "privileges": ["asset_management"]}' \
  | jq -r '.id')

# Add viewer relation
curl -X POST "https://api.beacontower.ai/relations" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d "{
    \"subjectType\": \"organization\",
    \"subjectId\": \"$VIEWER_ORG\",
    \"resourceType\": \"asset\",
    \"resourceId\": \"{asset-id}\",
    \"relation\": \"viewer\"
  }"

# Add manager relation
curl -X POST "https://api.beacontower.ai/relations" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d "{
    \"subjectType\": \"organization\",
    \"subjectId\": \"$MANAGER_ORG\",
    \"resourceType\": \"asset\",
    \"resourceId\": \"{asset-id}\",
    \"relation\": \"manager\"
  }"

Now assign users to the appropriate organization based on their required access level.

Best Practices

Organization Structure

Use functional organizations — Structure organizations by role or function (e.g., "Operations", "Maintenance", "Customer Support") rather than just mirroring company hierarchy
Plan privilege inheritance — Parent organizations should have all privileges that their children need
Separate customer data — Give each customer their own organization to ensure proper isolation

User Management

Use groups for permissions — Assign permissions to groups rather than individual users for easier management
Use groups for notifications — Create groups like "On-Call Engineers" or "Critical Alerts" to route notifications efficiently
Document access patterns — Keep track of which groups should have access to which resources

Security

Principle of least privilege — Grant only the minimum privileges required for each organization
Regular access reviews — Periodically review relations to ensure users still need their current access
Audit permission changes — Monitor who is creating and modifying relations, especially for sensitive resources

Performance

Batch permission checks — Use lookup-resources instead of checking permissions for individual resources in a loop
Cache permission results — Permission checks are fast but can add up; cache results when appropriate (with short TTL)
Limit organization depth — Very deep organization hierarchies can impact performance; keep to 4-5 levels maximum

Organization Templates — Pre-built organization structures for common scenarios
Alarms and Notifications — Configure alarm routing using groups and organizations
API Reference — Complete API documentation for all endpoints

Next Steps

Now that you understand organizations and permissions:

Design your organization structure based on your business needs
Create organizations and assign privileges
Add users and organize them into groups
Set up relations to grant access to resources
Configure alarm routing using groups (see Alarms and Notifications)

Understanding Tenants and Organizations​

Tenants​

Organizations​

Organization Hierarchy​

Creating Organizations​

Managing Organizations​

Organization Settings​

Users and Groups​

Users​

User Settings​

Groups​

Roles and Privileges​

Available Privileges​

Privilege Hierarchy​

Checking Privileges​

Auth Relations​

Relation Types​

Access Levels​

Creating Relations​

Finding Relations​

Deleting Relations​

Permissions in Practice​

How Access Works​

Permission Checks​

Check Permission​

Lookup Resources​

Lookup Subjects​

Different Access Levels for Different Users​

Best Practices​

Organization Structure​

User Management​

Security​

Performance​

Related Resources​

Next Steps​

Understanding Tenants and Organizations

Tenants

Organizations

Organization Hierarchy

Creating Organizations

Managing Organizations

Organization Settings

Users and Groups

Users

User Settings

Groups

Roles and Privileges

Available Privileges

Privilege Hierarchy

Checking Privileges

Auth Relations

Relation Types

Access Levels

Creating Relations

Finding Relations

Deleting Relations

Permissions in Practice

How Access Works

Permission Checks

Check Permission

Lookup Resources

Lookup Subjects

Different Access Levels for Different Users

Best Practices

Organization Structure

User Management

Security

Performance

Related Resources

Next Steps