Roles & Permissions API

Define roles with fine-grained permissions. Build flexible access control with role hierarchies and permission inheritance.

Endpoints

Method	Endpoint	Description
`GET`	`/roles`	List roles
`GET`	`/roles/:id`	Get role
`POST`	`/roles`	Create role
`PATCH`	`/roles/:id`	Update role
`DELETE`	`/roles/:id`	Delete role
`GET`	`/permissions`	List all permissions
`POST`	`/check-permission`	Check user permission

List Roles

GET /v1/organizations/:org/rolesbash

curl "https://api.accessiq.io/v1/organizations/acme-corp/roles" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": [
    {
      "id": "role_admin",
      "name": "Admin",
      "description": "Full administrative access",
      "type": "system",
      "permissions": [
        "users:*",
        "roles:*",
        "organizations:*",
        "settings:*"
      ],
      "userCount": 5,
      "createdAt": "2023-01-01T00:00:00Z"
    },
    {
      "id": "role_manager",
      "name": "Manager",
      "description": "Team management access",
      "type": "custom",
      "permissions": [
        "users:read",
        "users:write",
        "teams:*",
        "reports:read"
      ],
      "userCount": 25,
      "createdAt": "2023-06-15T10:00:00Z"
    },
    {
      "id": "role_member",
      "name": "Member",
      "description": "Standard user access",
      "type": "system",
      "permissions": [
        "profile:*",
        "teams:read"
      ],
      "userCount": 493,
      "createdAt": "2023-01-01T00:00:00Z"
    }
  ]
}

Get Role

GET /v1/organizations/:org/roles/:idbash

curl https://api.accessiq.io/v1/organizations/acme-corp/roles/role_manager \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": {
    "id": "role_manager",
    "name": "Manager",
    "description": "Team management access",
    "type": "custom",
    "permissions": [
      "users:read",
      "users:write",
      "teams:*",
      "reports:read"
    ],
    "inheritsFrom": ["role_member"],
    "conditions": {
      "teams": {
        "operator": "in",
        "value": ["${user.teams}"]
      }
    },
    "metadata": {
      "level": 2,
      "department": "all"
    },
    "users": [
      {
        "id": "user_abc123",
        "email": "john@acme.com",
        "displayName": "John Doe"
      }
    ],
    "userCount": 25,
    "createdAt": "2023-06-15T10:00:00Z",
    "updatedAt": "2024-01-10T14:00:00Z"
  }
}

Create Role

POST /v1/organizations/:org/rolesbash

curl -X POST https://api.accessiq.io/v1/organizations/acme-corp/roles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "description": "Customer support access",
    "permissions": [
      "users:read",
      "tickets:*",
      "knowledge-base:read"
    ],
    "inheritsFrom": ["role_member"],
    "conditions": {
      "department": {
        "operator": "equals",
        "value": "support"
      }
    },
    "metadata": {
      "level": 1,
      "department": "support"
    }
  }'

# Response (201 Created)
{
  "data": {
    "id": "role_support",
    "name": "Support Agent",
    "description": "Customer support access",
    "type": "custom",
    "permissions": [
      "users:read",
      "tickets:*",
      "knowledge-base:read",
      "profile:*",
      "teams:read"
    ],
    "inheritsFrom": ["role_member"],
    "userCount": 0,
    "createdAt": "2024-01-15T12:00:00Z"
  }
}

Permission Format

Permissions follow the resource:action pattern:

Permission	Description
`users:read`	View user information
`users:write`	Create and update users
`users:delete`	Delete users
`users:*`	All user operations
`*:read`	Read access to all resources
`:`	Full access (admin)

List All Permissions

GET /v1/organizations/:org/permissionsbash

curl https://api.accessiq.io/v1/organizations/acme-corp/permissions \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": {
    "users": {
      "actions": ["read", "write", "delete", "invite", "suspend"],
      "description": "User management"
    },
    "roles": {
      "actions": ["read", "write", "delete", "assign"],
      "description": "Role management"
    },
    "organizations": {
      "actions": ["read", "write", "delete", "invite"],
      "description": "Organization management"
    },
    "teams": {
      "actions": ["read", "write", "delete", "manage-members"],
      "description": "Team management"
    },
    "settings": {
      "actions": ["read", "write"],
      "description": "Organization settings"
    },
    "audit": {
      "actions": ["read", "export"],
      "description": "Audit logs"
    },
    "api-keys": {
      "actions": ["read", "write", "delete"],
      "description": "API key management"
    }
  }
}

Check Permission

Verify if a user has a specific permission:

POST /v1/organizations/:org/check-permissionbash

curl -X POST https://api.accessiq.io/v1/organizations/acme-corp/check-permission \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_abc123",
    "permission": "users:write",
    "resource": {
      "type": "user",
      "id": "user_def456"
    }
  }'

# Response
{
  "allowed": true,
  "reason": "Permission granted via role: Manager",
  "matchedRole": "role_manager",
  "effectivePermissions": [
    "users:read",
    "users:write",
    "teams:*"
  ]
}

Conditional Permissions

Define conditions that must be met for permissions to apply:

Role with Conditionsjson

{
  "name": "Team Lead",
  "permissions": ["users:*", "teams:*"],
  "conditions": {
    "teams": {
      "operator": "in",
      "value": ["${user.teams}"]
    },
    "department": {
      "operator": "equals",
      "value": "${user.department}"
    },
    "ipRange": {
      "operator": "in",
      "value": ["10.0.0.0/8", "192.168.0.0/16"]
    },
    "timeWindow": {
      "operator": "between",
      "value": ["09:00", "18:00"],
      "timezone": "America/New_York"
    }
  }
}

Condition Variables

Use ${user.property} to reference the current user's attributes in conditions for dynamic permission scoping.

Role Hierarchy

Roles can inherit permissions from other roles:

Role Inheritancejson

{
  "roles": [
    {
      "id": "role_member",
      "name": "Member",
      "permissions": ["profile:*", "teams:read"]
    },
    {
      "id": "role_manager",
      "name": "Manager",
      "inheritsFrom": ["role_member"],
      "permissions": ["users:read", "users:write", "teams:*"]
      // Effective: profile:*, teams:read, users:read, users:write, teams:*
    },
    {
      "id": "role_admin",
      "name": "Admin",
      "inheritsFrom": ["role_manager"],
      "permissions": ["*:*"]
      // Effective: All permissions
    }
  ]
}

Role Schema

Role Objecttypescript

interface Role {
  id: string;
  name: string;
  description?: string;
  type: 'system' | 'custom';
  permissions: string[];
  inheritsFrom?: string[];
  conditions?: Record<string, Condition>;
  metadata?: Record<string, any>;
  userCount: number;
  createdAt: string;
  updatedAt: string;
}

interface Condition {
  operator: 'equals' | 'in' | 'not_in' | 'between' | 'contains';
  value: string | string[];
  timezone?: string;
}

System Roles

System roles (Admin, Member) cannot be deleted but can have their permissions modified. Use caution when modifying system role permissions.