Customer Setup Guide
ZEN for Revit
Make standards executable
Install ZEN, create APS credentials, register the integration in ACC, enter your credentials, and verify the connection.
1
Install ZEN
2
Create APS App
3
Add to ACC
4
Enter Credentials
5
Ping & Validate
Purpose & Roles
This guide is written for a new customer who needs to install ZEN and connect it to Autodesk Construction Cloud (ACC) through Autodesk Platform Services (APS). It assumes you are starting from scratch and have not previously created APS credentials for ZEN.
Who should perform each step
| Role | Responsible for |
|---|---|
| APS App Owner / BIM Manager | Creating the APS application and recording credentials |
| ACC Hub Administrator | Registering the APS Client ID in ACC Custom Integrations |
| Technical Admin / BIM Manager | Installing ZEN, entering credentials, running the connection test |
⚠ Important:If one person does not hold all three roles, coordinate the steps before starting. Missing admin rights or missing credentials are the most common reasons setup fails.
Setup Overview
The setup has two clearly separate parts. Understanding this distinction before you begin prevents the most common mistakes:
- APS creates the application identity — a Client ID and a Client Secret.
- ACC grants that application access to your hub through Custom Integrations.
- ZEN uses the Client ID and Client Secret to request an APS token and access permitted ACC data.
⚠ Important:ACC Custom Integrations do not create APS credentials. You must create the APS application first. The Client ID is then registered in ACC. The Client Secret is entered only into ZEN — never into ACC.
Prerequisites
Confirm all of the following before starting.
| Requirement | Needed for | Notes |
|---|---|---|
| Autodesk account | APS developer portal and ACC access | Use a customer-owned account wherever possible. |
| ACC / Autodesk Docs access | Hub, projects, folders, model files | Autodesk Docs is sufficient for basic connection testing. |
| ACC Hub Admin rights | Registering the Client ID in Custom Integrations | Found under Hub Admin > Custom Integrations. |
| APS Developer Portal access | Creating the Client ID and Client Secret | APS credentials must be created before the ACC step. |
| Autodesk Revit 2024, 2025, or 2026 | Running ZEN commands | Install the ZEN build matching your Revit version. |
| Windows 10 or 11 (64-bit) | ZEN installation | Administrator rights required during install. |
| Autodesk Desktop Connector | Accessing ACC cloud models from Revit | Must be installed and signed in before batch operations. |
1
Install ZEN in Revit
- Close all running Revit sessions before starting the installer.
- Obtain the ZEN installer for your Revit version from your BIM manager. Example:
ZEN_Installer_2025_1.0.0.exe - Right-click the installer and choose Run as Administrator.
- Accept the license agreement and follow the setup wizard to completion.
- Click Finish. Do not launch Revit yet — credentials have not been entered.
⚠ Important:If a previous ZEN version is installed, uninstall it first via Windows Settings → Apps before running the new installer.
What the installer places on disk
| File / Folder | Location |
|---|---|
| ZEN binaries folder | C:\ProgramData\Autodesk\Revit\Addins\20XX\ZEN\ |
| ZEN add-in manifest | C:\ProgramData\Autodesk\Revit\Addins\20XX\ZEN.addin |
| APS credentials config file | C:\ProgramData\Autodesk\Revit\Addins\20XX\ZEN\ZEN.dll.config |
| Default model registry folder | C:\ZEN\Data\ |
Replace 20XX with your Revit version number, e.g. 2025.
2
Create the APS Application
This step creates the credentials ZEN uses to authenticate with Autodesk. Perform this step before touching ACC or ZEN settings.
- Go to aps.autodesk.com and sign in with the Autodesk account that will own this integration.
- Navigate to My Apps and click Create application.
- Fill in the application details:
- App Name: e.g. ZEN Integration
- App Type: Server-to-Server App (2-legged OAuth)
- Under API access, enable these scopes:
data:read account:read
- Click Create application. The portal displays your Client ID and Client Secret.
- Copy both values immediately and store them securely. The Client Secret is shown only once.
⚠ Important:Do not enable write scopes unless a future ZEN feature explicitly requires them.
Credential reference
| Credential | Purpose | Where it goes |
|---|---|---|
| Client ID | Public identifier for the APS application | Pasted into ACC Custom Integrations and entered into ZEN |
| Client Secret | Secret used by ZEN to request APS tokens | ZEN only. Never pasted into ACC. |
⚠ Important:Treat the Client Secret like a password. Do not send it by plain email. If it is exposed, regenerate it in the APS portal and update ZEN immediately.
3
Register the APS App in ACC Custom Integrations
This step grants the APS application access to your ACC hub. Performed by an ACC Hub Administrator.
- Open acc.autodesk.com and sign in.
- Confirm you are in the correct hub using the account switcher at the top.
- Click Hub Admin in the left navigation.
- Open Custom Integrations.
- Click Add custom integration.
- Paste the APS Client ID from Step 2 into the Autodesk Platform Services Client ID field.
- Enter a clear integration name, e.g. ZEN Integration.
- Add a description: ZEN APS integration for ACC model registry, cloud access, and batch automation.
- Click Next and complete the access selection screens.
- Grant access for Document Management / ACC Docs and related data operations.
- Save. Confirm the entry shows status Active.
□ Tip:Include the APS app name in the description — some ACC screens don't show the Client ID clearly after saving.
⚠ Important:Only an ACC Hub Administrator can complete this step. If you lack permissions, provide your Client ID to your ACC admin and ask them to complete Step 3.
4
Enter Credentials into ZEN
ZEN reads APS credentials from a configuration file on disk. There is no in-app settings screen — you edit the file directly using Notepad or any plain text editor.
Locate the configuration file
Open this file in Notepad:
C:\ProgramData\Autodesk\Revit\Addins\2025\ZEN\ZEN.dll.configFor Revit 2024 or 2026, replace 2025 with the matching version number.
Enter your credentials
Find the two lines below and replace the placeholder values with your actual Client ID and Client Secret:
<add key="ApsClientId" value="PASTE-YOUR-CLIENT-ID-HERE" />
<add key="ApsClientSecret" value="PASTE-YOUR-CLIENT-SECRET-HERE" />Save the file and close the text editor.
□ Tip:Alternatively, set Windows environment variables named
ApsClientId and ApsClientSecret. ZEN reads these as a fallback when the config file values are blank.
Launch Revit and confirm the ZEN ribbon
- Open Revit.
- Look for the ZEN tab in the ribbon. It should contain: Project Setup & Coordinates, Sheets, Schedules & Excel, Worksets & Links, Parameters & Keynotes, QA & Diagnostics, Lab, Families & Library, and ACC Gate.
- If the tab is missing, confirm the
.addinmanifest exists at the path above and that Revit was fully closed before the install completed.
5
Ping & Validate the Connection
Run the built-in connection test before attempting any cloud operations.
Run the APS token test
- In Revit, go to the ZEN tab → ACC Gate panel.
- Click Test APS Token.
- A dialog appears. A green tick and a partial token string confirm success.
✅ Success:Token retrieved — ZEN can authenticate with APS. Proceed to the validation workflow below.
⚠ Important:If the test fails, do not continue to cloud linking or batch operations. Use the troubleshooting checklist below first.
Prepare a first ACC test project
- Use a small project with 2 to 5 Revit models — do not start with a large batch.
- Confirm the models are visible in ACC Docs and accessible to the account used during setup.
- Ensure Autodesk Desktop Connector is installed, signed in, and has synced the models locally.
First ZEN validation workflow
- Go to ZEN → ACC Gate.
- Load the ACC Model Registry CSV. If you don't have one yet, use Cloud GUIDs to generate an initial registry from an open ACC model.
- Select your test hub and project from the picker.
- Select 2 to 5 models.
- Run a non-destructive command first — e.g. model metadata read or health report.
- Only after validation succeeds, proceed to cloud linking, workset creation, or batch operations.
□ Tip:To get the correct ApsProjectId and ApsItemUrn values, open an ACC cloud model in Revit and run ZEN → ACC Gate → Cloud GUIDs. ZEN writes a ready-to-use CSV row with the correct column values.
Testing with Postman Optional
Postman is not required for day-to-day ZEN use. However, it is strongly recommended during initial setup and troubleshooting to isolate credential problems quickly.
When to use Postman
| Situation | Use Postman? |
|---|---|
| Day-to-day ZEN use | No — ZEN handles this automatically |
| First-time setup credential check | Yes — recommended before entering into ZEN |
| Diagnosing 401 / 403 errors in ZEN | Yes — fastest way to isolate the problem |
| Validating project or item URNs | Yes — optional but useful |
Request a token in Postman
Create a new POST request:
| Field | Value |
|---|---|
| URL | https://developer.api.autodesk.com/authentication/v2/token |
| Body type | x-www-form-urlencoded |
| client_id | Your APS Client ID |
| client_secret | Your APS Client Secret |
| grant_type | client_credentials |
| scope | data:read account:read |
A successful HTTP 200 response contains an access_token. HTTP 401 means the credentials are wrong. HTTP 400 with invalid_scope means the scope field doesn't match exactly.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| ACC Add Custom Integration won't continue | Client ID missing or copied incorrectly | Copy the Client ID from the APS app again. Do not paste the Client Secret here. |
| ZEN Test APS Token fails immediately | Client Secret missing, invalid, or recently regenerated | Paste the current Client Secret into ZEN.dll.config. Regenerate in APS if needed. |
| Ping succeeds but model access fails | ACC Custom Integration access is incomplete | Confirm Document Management access is granted in the integration settings. |
| Cannot find Custom Integrations | Not Hub Admin or in wrong hub | Switch to the correct hub and use a Hub Admin account. |
| Wrong project or no models visible | Project access or folder permission issue | Confirm project membership, folder permissions, and model visibility in ACC Docs. |
| ZEN tab missing from Revit ribbon | Installer incomplete or wrong Revit version | Confirm the .addin manifest exists in the correct Addins folder. |
| Token was working, now fails | Client Secret regenerated in APS without updating ZEN | Paste the new Client Secret into ZEN.dll.config and restart Revit. |
Security & Responsibility Notes
- The customer should own the APS app credentials in their own environment.
- The Client Secret must not be sent by plain email or stored in uncontrolled documents.
- If a credential is exposed, regenerate immediately in the APS portal, update
ZEN.dll.config, and restart Revit. - Limit ACC hub and project access according to your BIM governance rules.
- For support sessions, screen-sharing is preferable to transmitting credential values.
- Restrict file system read access to
ZEN.dll.config— treat it as a credential file.
Customer Completion Checklist
Click each item to mark it complete.
- ZEN installed for the correct Revit version.
- ZEN ribbon (ZEN tab) is visible in Revit.
- APS application created with correct app type (Server-to-Server).
- APS scopes set to
data:readandaccount:read. - Client ID recorded securely.
- Client Secret stored securely (shown once — do not lose it).
- APS Client ID added to ACC Custom Integrations.
- ACC integration access options completed (Document Management granted).
- Client ID and Client Secret entered into
ZEN.dll.config. - Test APS Token returns a successful result in ZEN.
- Small ACC test project (2–5 models) validated successfully.
- First non-destructive ZEN cloud command completed (e.g. model metadata or health report).
Quick Reference
Key file locations
| File | Path |
|---|---|
| ZEN binaries folder | C:\ProgramData\Autodesk\Revit\Addins\20XX\ZEN\ |
| ZEN add-in manifest | C:\ProgramData\Autodesk\Revit\Addins\20XX\ZEN.addin |
| APS credentials config | ...\ZEN\ZEN.dll.config (keys: ApsClientId, ApsClientSecret) |
| Model registry default | C:\ZEN\Data\ACC_Model_Registry.csv |
| Batch run log | Output folder → ZEN_ACC_Gate_BatchRun_*.txt |
Key URLs
APS Developer Portal
APS Token Endpoint
developer.api.autodesk.com/authentication/v2/token
Autodesk Construction Cloud
APS Getting Started
APS OAuth Overview
APS OAuth Scopes
ZEN ribbon — ACC Gate panel buttons
| Button label | Purpose |
|---|---|
| Test APS Token | Verifies credentials and APS connectivity. Run this first after entering credentials. |
| ACC Gate | Opens the cloud batch engine — model picker, action selector, and batch runner. |
| Cloud GUIDs | Reads ProjectGuid and ModelGuid from the active ACC cloud model and writes a registry CSV row. |
| Export Cloud Link Matrix | Generates the cloud link matrix from the model registry. |
| Edit Cloud Link Matrix | Opens the cloud link matrix editor form. |
| ACC Refresh Sizes | Updates StorageSizeBytes and VersionId in the registry CSV via APS. |