SSA (2LO) cannot access ACC file contents while 3LO works – what APS permissions or app settings are required?

by

Summary

This postmortem analyzes the integration of Autodesk Construction Cloud (ACC) with FME Flow using Secure Service Accounts (SSA / 2LO). The core failure is that while service account authentication (2LO) successfully lists project metadata, it fails to access or download file contents. This behavior contradicts the expectation that SSA provides full unattended automation capabilities comparable to 3LO (user-based OAuth). The root cause lies in the nuanced difference between product-level permissions (BIM 360/ACC roles) and data management scope authorization, combined with the current limitations of SSA regarding file permissions.

Root Cause

The inability to access file contents via SSA (2LO) stems from three primary factors:

  • Scope Insufficiency: The APS app configuration is likely missing the specific data management scope required for file operations. Listing hubs and projects requires data:read, but accessing file contents typically requires viewables:read or broader data management permissions depending on the API endpoint used.
  • Permission Inheritance vs. Explicit Grants: While the SSA is added to the ACC project, product-level roles (e.g., Viewer, Project Admin) do not automatically translate to full data access rights in the Data Management API. The SSA might have “view” access to the project container but lacks explicit permission on the specific files or versions.
  • SSA “Public” vs. “Private” Scope Limitations: Historically, 2LO (Client Credentials) flows are treated as “public” applications. ACC file permissions are often tied to a specific user context. If the file permissions are not explicitly shared with the “All Users” public group or the specific service account email, the API returns a 403 Forbidden for content access, even if the listing works.

Why This Happens in Real Systems

In complex enterprise ecosystems, authentication and authorization are decoupled. This creates the exact scenario described in the input:

  1. API Layering: Autodesk APIs are layered. The BIM 360/ACC API handles project structure (hubs/projects/folders), while the Data Management API handles actual file objects (versions/contents). These layers enforce permissions differently.
  2. Security by Default: Service accounts (SSA) are designed to be least-privilege. Unlike a human user (3LO) who inherits broad project permissions, a robot account must be explicitly granted scopes and data permissions.
  3. Token Scope Mismatch: A token obtained via 2LO (Client Credentials) is scoped strictly to the APS app’s defined scopes. If the app configuration lacks the viewables:read scope (or equivalent for direct download), the token is invalid for file content endpoints, resulting in a confusing “Listing works, Download fails” state.

Real-World Impact

  • Automation Blockage: The primary goal of moving to SSA—unattended, headless automation—is blocked. The system cannot perform its core function of downloading files without manual intervention.
  • Operational Overhead: Reliance on 3LO requires maintaining a user account with 2FA, creating a “break glass” dependency on a human identity for scheduled tasks.
  • Security Compliance Risks: Using user-based OAuth (3LO) for server-to-server automation often violates security policies that mandate distinct service identities for auditing and access control.

Example or Code

To diagnose the issue, you must verify the token scopes and the API response codes. Below is a Python example using the forge-apis SDK to check token validity and attempt file access.

import os
from autodesk_app_index_client.rest import ApiException
from forge_sdk import AuthClientTwoLegged, DataManagementApi

def check_ssa_access(client_id, client_secret, file_id):
    # 1. Establish 2LO (Client Credentials) authentication
    auth = AuthClientTwoLegged(client_id, client_secret, ["data:read", "viewables:read"])

    try:
        # 2. Get token
        token = auth.authenticate()
        print(f"Token Scopes: {token.scope}")

        # 3. Attempt to get file versions (Metadata)
        dm_api = DataManagementApi()
        versions = dm_api.get_file_versions(file_id, {}, _access_token=token.access_token)
        print("File versions retrieved successfully.")

        # 4. Attempt to download content (The failure point)
        # If this raises an exception, check the status code (likely 403)
        content_response = dm_api.get_file_content(file_id, {}, _access_token=token.access_token)
        print("File content downloaded successfully.")

    except ApiException as e:
        print(f"API Exception: {e.status} - {e.reason}")
        print("Check scopes in APS dashboard and permissions in ACC.")

# Usage
# check_ssa_access("your_client_id", "your_client_secret", "urn:adsk.wipprod:fs:file:...")

How Senior Engineers Fix It

Senior engineers approach this by separating authentication debugging from permission debugging:

  1. Validate APS App Scopes:
    • Log in to the APS Developer Portal.
    • Ensure the app configuration for the SSA includes data:read (for listing) and viewables:read (specifically for viewing/downloading file versions). If using the Data Management API specifically for download, ensure data:write is not strictly required but data:read is explicit.
  2. Explicit Data Permission Grant:
    • Do not rely solely on the project role. You must explicitly share the specific folder or file with the SSA’s email address (the robot account email, e.g., s-fme_forge@...adskserviceaccount.com) within the ACC/BIM 360 interface.
    • Alternatively, ensure the parent folder is shared with “All Project Members” (if policy allows), which includes the SSA.
  3. Verify API Endpoint:
    • Ensure FME is calling the correct endpoint for download. The endpoint must be the Data Management API GET :/derivatives/{derivativeUrn} for viewing, or GET :/data/v1/projects/{project_id}/items/{item_id}/versions/{version_id}/content for direct download.
  4. Re-authenticate:
    • After changing scopes in the APS portal, the client secret does not change, but the token payload might reflect new scopes. Ensure the application restarts to pick up any new environment variables if client IDs were rotated.

Why Juniors Miss It

Junior engineers often struggle with this specific issue because of the “Fallacy of Equivalent Access.”

  1. Confusing Product Roles with API Scopes: They assume that adding the SSA to the ACC project as a “Viewer” grants automatic API access. They fail to realize that API access is governed by OAuth scopes defined in the APS portal, independent of the ACC product role.
  2. Lack of Token Inspection: They often stop at the “Listing works” step, assuming the connection is valid. They fail to inspect the OAuth token scopes or debug the specific HTTP 403 error returned by the Data Management API.
  3. Misinterpreting “GA” (General Availability): Reading “SSA is GA” leads to the assumption that it feature-parity with 3LO. Seniors know that “GA” often refers to the availability of the account type, not the immediate availability of all permission nuances across disparate Autodesk services.