ACC API: Best Practices for Accessing and Assigning Roles in ACC Projects

Autodesk Construction Cloud (ACC) provides APIs for managing users, projects, and roles. While testing the ACC Roles API, I identified several gaps that impact role management workflows. This post outlines the issues, unexpected behaviors, and practical workarounds that can help developers handle roles effectively.

Accessing Account Roles via API

The official documentation states that the endpoint GET projects/:project_id/industry_roles is not supported for ACC projects.

However, in practice, this endpoint does return account roles for ACC projects. While useful, this behavior has risks since it is undocumented and may be changed or disabled by Autodesk at any time. At present, there is no other officially supported endpoint that directly provides account role details for ACC.

Issues with Deleted or Removed Roles

Visibility Issue: Deleted roles appear in API responses alongside active ones. Since there is no property that differentiates them, developers cannot reliably filter roles by status.
- Reported in ticket: ACSAA-5817 (API returns all roles, including deleted ones).
Assignment of Deleted Roles: Deleted or removed roles can still be assigned to users through the API if their role ID is known. A POST projects/:projectId/users request will successfully assign a deleted role, despite this being restricted in the ACC UI.
When such a role is assigned, a subsequent GET projects/{projectId}/users request may return a response like:
```
"roles": [
  {
    "id": "55a623b3-0584-43f2-a5ef-883a74ff99ea",
    "name": "Test Role (Removed)",
    "roleGroupId": "529219262"
  }
]
```
As shown above, the keyword "Removed" appears in the role name, indicating that the role no longer exists in account roles but is still assigned.
- Reported in ticket: AECMA-5937 (API allows assignment of deleted roles).

Workarounds and Solutions

Question: Is there a way to access only active account roles?

Answer: Yes. As mentioned in the ACC API documentation, the recommended approach is to use the Data Connector API, which provides role information with status included.

The Data Connector offers a roles schema that clearly indicates whether a role is active or inactive. Refer to the Data Connector Roles Schema .
This allows developers to reliably distinguish active and inactive roles.
In my tests, the admin_project_roles.csv file from the Data Connector API provides comprehensive details of account roles, making it easy to identify active vs. inactive ones.

Key Takeaways

Issue: Deleted roles are returned by the Roles API and can still be assigned via API calls, contrary to ACC UI behavior.
Workarounds:
- Check role names for the keyword "Removed".
- Use the Data Connector API to reliably identify role status.
Best Practice: Always use the Data Connector API to distinguish between active and inactive roles, and ensure inactive ones are not assigned to users.