Access Control

Implement fine-grained access control with roles, permissions, and policies. AccessIQ provides flexible RBAC that scales from simple to complex authorization requirements.

Overview

AccessIQ's access control system is built on three core concepts:

Permissions

Granular actions that can be performed on resources

Roles

Collections of permissions assigned to users

Policies

Conditional rules for dynamic access decisions

Permissions

Permissions follow a resource:action naming convention. Define permissions that match your application's domain model.

Example Permissionstypescript

// Permission structure
{
  "permissions": [
    "users:read",        // View user data
    "users:write",       // Create/update users
    "users:delete",      // Delete users
    "roles:manage",      // Manage role definitions
    "billing:view",      // View billing information
    "billing:manage",    // Manage billing settings
    "settings:read",     // View organization settings
    "settings:write",    // Modify organization settings
    "reports:export"     // Export data reports
  ]
}

Permission Naming

Use consistent naming patterns. We recommend resource:action format where action is one of: read, write, delete, manage, export, etc.

Roles

Roles are named collections of permissions. Users are assigned roles rather than individual permissions.

Create Role APIbash

curl -X POST https://api.accessiq.io/v1/roles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project Manager",
    "description": "Manages projects and team members",
    "permissions": [
      "users:read",
      "users:write",
      "projects:read",
      "projects:write",
      "reports:export"
    ],
    "isDefault": false
  }'

Default Roles

AccessIQ provides built-in roles that you can use or customize:

Owner

Full access to all resources, can manage billing and delete organization

Admin

Administrative access, can manage users and settings

Member

Standard access to organization resources

Viewer

Read-only access to resources

Checking Permissions

Permissions are included in the JWT token claims. Check permissions in your application:

lib/permissions.tstypescript

import { getSession } from '@/lib/auth'

export function hasPermission(
  permissions: string[],
  required: string
): boolean {
  return permissions.includes(required)
}

export function hasAnyPermission(
  permissions: string[],
  required: string[]
): boolean {
  return required.some(p => permissions.includes(p))
}

export function hasAllPermissions(
  permissions: string[],
  required: string[]
): boolean {
  return required.every(p => permissions.includes(p))
}

// Usage in API route
export async function GET(request: Request) {
  const session = await getSession()

  if (!hasPermission(session.permissions, 'users:read')) {
    return new Response('Forbidden', { status: 403 })
  }

  // ... handle request
}

Role Hierarchies

Roles can be scoped at different levels for maximum flexibility:

Tenant Roles

Defined at the platform level, available to all organizations. Ideal for standard roles that apply across your customer base.

Organization Roles

Custom roles defined by individual organizations. Allows customers to create roles specific to their internal structure.

Best Practices

Start with minimal permissions and add more as needed
Use descriptive role names that match your domain
Avoid giving users direct permissions; use roles instead
Document what each permission allows
Regularly audit role assignments