Authorization

After authentication, authorization determines what actions a user or service can perform. This guide covers our role-based access control (RBAC) system and permission model.

Authorization Model

The Powerverse Platform API uses a hierarchical authorization model:

Organization
    └── Roles (Admin, Operator, Viewer, etc.)
           └── Permissions (read:sites, write:assets, etc.)
                  └── Resources (specific sites, assets, etc.)

Roles

Built-in Roles

Role	Description	Typical Use
owner	Full access, can manage billing	Organization owners
admin	Full API access, can manage members	Platform administrators
operator	Standard access to manage resources	Site operators and technicians
viewer	Read-only access	Auditors, stakeholders
service	Machine-to-machine access	Automated systems

Role Hierarchy

owner (inherits all)
  └── admin (inherits operator)
        └── operator (inherits viewer)
              └── viewer (base permissions)

Permissions

Permissions follow the pattern: action:resource

Permission Actions

Action	Description
read	View resources
write	Create and update resources
delete	Remove resources
admin	Full control including settings

Resource Permissions

Site Permissions

• read:sites - List and view sites
• write:sites - Create and update sites
• delete:sites - Remove sites
• admin:sites - Manage site settings and configuration

Asset Permissions

• read:assets - List and view assets
• write:assets - Create and update assets
• delete:assets - Remove assets
• admin:assets - Manage asset configuration

Schedule Permissions

• read:schedules - View schedules and schedule items
• write:schedules - Create and update schedules
• delete:schedules - Remove schedules
• admin:schedules - Manage schedule settings

Session Permissions

• read:sessions - View sessions
• write:sessions - Perform session actions
• read:events - View event history

Checking Permissions

In API Responses

Resources include permission hints in the response:

{
  "data": {
    "id": "sit_abc123",
    "name": "London Charging Hub",
    "status": "active"
  },
  "meta": {
    "permissions": {
      "can_update": true,
      "can_delete": false,
      "can_manage_settings": false
    }
  }
}

Current User Permissions

Fetch your current permissions:

curl -X GET "https://platform.powerverse.com/auth/permissions" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "data": {
    "roles": ["operator"],
    "permissions": [
      "read:sites",
      "write:sites",
      "read:assets",
      "write:assets",
      "read:schedules",
      "write:schedules",
      "read:sessions",
      "read:events"
    ],
    "scopes": [
      "read:sites",
      "write:assets"
    ]
  }
}

Resource-Level Authorization

Beyond role-based permissions, access may be restricted to specific resources.

Ownership

Users can only access resources they own or that belong to their organization:

# ✅ Access your organization's site
GET /inventory-service/sites/sit_abc123  # Your org's site

# ❌ Cannot access other organization's sites
GET /inventory-service/sites/sit_other456  # Returns 403 Forbidden

Organization Scope

Resources are scoped to organizations:

# Only returns assets for your organization
GET /inventory-service/assets

# Cannot access assets from other organizations
GET /inventory-service/assets?organization_id=other_org  # Returns 403

Site-Based Access

Some resources support site-based access control:

{
  "id": "ast_xyz",
  "name": "EV Charger Unit A",
  "site_id": "sit_123",
  "visibility": "site"
}

OAuth Scopes

When using OAuth 2.0, requested scopes limit the permissions:

Token Permissions = Role Permissions ∩ Requested Scopes

Example:

• User role: admin (has read:assets, write:assets, delete:assets)
• OAuth scopes: read:assets write:assets
• Effective permissions: read:assets, write:assets (no delete:assets)

Scope Request Example

# Request limited scopes
GET /oauth2/authorize?
  scope=read:sites%20read:assets&
  ...

Error Handling

403 Forbidden - Insufficient Permissions

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You don't have permission to perform this action",
    "details": {
      "required_permission": "write:schedules",
      "your_permissions": ["read:schedules"]
    }
  }
}

403 Forbidden - Resource Not Accessible

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You don't have access to this resource",
    "details": {
      "resource_type": "Site",
      "resource_id": "sit_xyz789",
      "reason": "belongs_to_different_organization"
    }
  }
}

Best Practices

Principle of Least Privilege

Request only the permissions you need:

# ❌ Don't request admin scope if you only need to read
scope=admin

# ✅ Request specific, minimal scopes
scope=read:sites read:assets

Handle Permission Errors Gracefully

try {
  const response = await api.deleteAsset(assetId);
} catch (error) {
  if (error.status === 403) {
    // Show appropriate UI message
    showError("You don't have permission to delete assets");
    // Optionally hide the delete button
    hideDeleteButton();
  }
}

Cache Permissions Appropriately

// Fetch permissions once per session
const permissions = await api.getPermissions();

// Check locally before making requests
function canDeleteAsset() {
  return permissions.includes('delete:assets');
}

Admin API

Organization admins can manage roles and permissions via the Admin API:

List Organization Members

curl -X GET "https://platform.powerverse.com/admin/members" \
  -H "Authorization: Bearer ADMIN_TOKEN"

Update Member Role

curl -X PATCH "https://platform.powerverse.com/admin/members/mbr_abc123" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'

Create Custom Role

curl -X POST "https://platform.powerverse.com/admin/roles" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "site_manager",
    "display_name": "Site Manager",
    "permissions": [
      "read:sites",
      "write:sites",
      "read:assets",
      "write:assets",
      "read:schedules"
    ]
  }'

Next Steps

• API Keys - Managing API key permissions
• Rate Limits - Understanding rate limiting
• Error Handling - Handling authorization errors