Skip to main content

List Role

GET 
/api/v1/infra/collections/:collectionId/roles

Retrieves a paginated list of all IAM roles assigned to a specific user within a collection. Returns role summaries including names, types, permissions scope, and assignment details for access management review.

Path Parameter Note: If the collections list returns a "provider not supported" error code, use "default" as the collectionId value.

Parameter Details​

Header Parameters​

  • integrationid (required): Unique identifier for the cloud provider integration configured in your Unizo account. This UUID associates the API request with the specific cloud account credentials and permissions. Use the integration ID from your Unizo dashboard under Connectors → [Provider] → Integration Details.

Path Parameters​

  • collectionId (required): Unique identifier for the collection within the specified cloud provider. Format varies by provider:

    • AWS: Region identifier for compliance environments (e.g., us-east-1 for US compliance, eu-west-1 for GDPR compliance)
    • Google Cloud: Project ID for governance environments (e.g., prod-compliance-env, audit-data-project-2024)
    • Azure: Use "default" when no specific subscription or resource group mapping is configured
    • Other providers: Provider-specific collection identifiers

  • userId (required): Unique identifier for the user account within the cloud provider's identity system. Format examples:

    • AWS: IAM user name for GRC roles (e.g., compliance-auditor, security-analyst, governance-admin) or ARN
    • Google Cloud: Email address for audit team members (e.g., auditor@company.com, compliance@company.com) or user ID
    • Azure: User principal name for GRC team (e.g., grc-team@company.com, audit.admin@company.com) or object ID
    • Other providers: Provider-specific user identifiers

Query Parameters​

  • offset: Starting position for pagination (default: 0). Use this to skip a specific number of role records during access reviews and privilege audits. For example, offset=20 starts from the 21st role for comprehensive governance assessments.

  • limit: Maximum number of roles to return per page (default: 50, max: 200). Optimize performance by requesting only the number of records you need for compliance reporting and security reviews.

  • sort: Sort roles by field name for access management analysis. Use field names directly (e.g., name) or prefix with - for descending order (e.g., -name). Multiple fields supported for audit workflows: name,-type,description.

Request​

Responses​

Successful Operation