Skip to main content

Autodesk Platform Services

Autodesk Platform Services (APS) can be integrated with VIKTOR using the OAuth 2.0 workflow for token based authentication and authorization. A general introduction to OAuth 2.0 can be found here.

Creating an OAuth 2.0 integration (admin)​

First, an OAuth 2.0 integration must be set up by a VIKTOR admin. This must be done in APS and in VIKTOR, following these steps:

  1. Navigate to the Integrations tab in the Administrator panel.

  2. Select the OAuth 2.0 tab.

  3. Follow the steps in the modal:

    1. Select Autodesk Platform Services.
    2. Go to the "Basic Information" tab and fill the required fields, including the integration name, and select the applications that will use the APS integration.
    3. Then, in the "Configuration" tab add the Authentication URL and Token URL as follows:
    4. If you already have an active APS application, you can fill in the client ID and secret, as well as the scopes and expiration date, if you do not have one, continue to the next step to create and set up the APS application.

  4. On the APS home page, go to your profile and click Applications.

    1. You can create a new application following this tutorial: Create an app.
    2. Or you can use an existing application.

  5. In the APS application, open App settings and copy Client ID and Client Secret into the VIKTOR modal from step 3.

  6. Go to General settings and add the callback URL:

    <your-viktor-environment-url>/api/integrations/oauth2/callback/

    Your environment URL should be https://cloud.viktor.ai/ or similar, depending on your organization.

  7. Open App access and select the APIs you want your application to access.

  8. Save the configuration in each section and verify that everything is correctly set up.

Defining Scopes for APS applications​

A scope defines what a token can do, it is the permission context for the token. A token that includes data:read can read data in APS, and it works with endpoints that require that scope. A token that lacks the scope cannot access those endpoints. Each endpoint page states the scopes it needs.

The APS documentation lists all scope values in the Scopes section: APS OAuth 2.0 scopes. Common scopes include:

  • data:read
  • data:write
  • data:create
  • code:all
  • data:search
  • viewables:read
Security best practices

Use the minimum scopes required for your application to function when creating the integration in VIKTOR. This limits the impact in case of misuse.

Integration with Autodesk Construction Cloud (ACC)​

Your VIKTOR-APS integration can connect to Autodesk Construction Cloud using Custom integrations. A custom integration connects your Autodesk Construction Cloud account to your APS application.

The user must be an Account Admin to add the app integration. Follow these steps to connect your APS application to your ACC projects:

  1. Log in to your ACC account.

  2. Open Custom integrations and click Add custom integration.

  3. Enter the APS Client ID from the previous section.

  4. Enter a name and a description for the custom integration.

  5. Complete the integration by clicking Add app.

Implementing the integration in an app (developer)​

Once an administrator sets up and assigns the APS OAuth 2.0 integration to the app, the developer can start the implementation.

The developer should add the integration name to the app configuration. The platform uses it to show a login button when the user opens the app. Make sure your viktor.config.toml contains the name exactly as configured in the Administrator panel, and include an oauth2_integrations entry with the integration name, for example:

viktor.config.toml:

app_type = "editor"
python_version = "3.13"
registered_name = "your-app-name"
oauth2_integrations = [
    "aps-integration-1"
]
Note

The OAuth2Integration can only be used in local development. The AppBuilder does not support this integration yet.

Then implement the logic that uses the integration in the code. You can use raw REST requests or a Python SDK, as long as it is compatible with the VIKTOR OAuth flow. A popular library is requests. You can add it in your requirements.txt to use it in the application.

viktor==14.24.1
requests

To obtain an access token, instantiate OAuth2Integration with the integration name and call get_access_token. Below is a short example showing how to retrieve the user’s available hubs and display them in a TableView. It works when the VIKTOR APS integration is assigned to your app, the ACC custom integration is added to your account, and the user has granted access:

import viktor as vkt
import requests

class Parametrization(vkt.Parametrization):
    text = vkt.Text("# APS OAuth2 Integration")

class Controller(vkt.Controller):
    parametrization = Parametrization

    @vkt.TableView("Get ACC Hubs")
    def get_hubs(self, params, **kwargs):
        integration = vkt.external.OAuth2Integration("aps-integration-1")
        token = integration.get_access_token()

        headers = {"Authorization": f"Bearer {token}"}
        endpoint = "https://developer.api.autodesk.com/project/v1/hubs"
        response = requests.get(endpoint, headers=headers, timeout=15)
        response.raise_for_status()

        hubs_data = response.json().get("data", [])

        data = []
        for hub in hubs_data:
            hub_name = hub.get("attributes", {}).get("name", "")
            hub_id = hub.get("id", "")
            data.append([hub_name, hub_id])

        return vkt.TableResult(data, column_headers=["Hub name", "ID"])
Note

The integration name in OAuth2Integration must match the value in viktor.config.toml. The ACC custom integration must be added in Account Admin, and the user must have access to projects in that account.