Connect-APS

Authenticates via OAuth and prepares a connection for communicating to Autodesk Platform Services (APS) using 3-Legged access tokens.

Syntax

Connect-APS [-User <String>] [<CommonParameters>]
<#
PARAMETER
    -User
        Required                false

    <CommonParameters>
        This cmdlet supports the common parameters: ErrorAction, ErrorVariable
#>

To use your own Autodesk app credentials for access to premium APIs:

Connect-FLC -ClientId <String> [-ClientSecret <String>] [-CallbackUrl <Uri>] [-User <String>] [<CommonParameters>]
<#
PARAMETER
    -ClientId
        Required                true

    -ClientSecret
        Required                false

    -CallbackUrl
        Required                false

    -User
        Required                false

    <CommonParameters>
        This cmdlet supports the common parameters: ErrorAction, ErrorVariable
#>

Parameters

Type	Name	Description	Default value
String	User	Email address of the Autodesk user to impersonate when running on the Job Processor. APS calls will be executed on behalf of this Autodesk ID	The Autodesk ID signed in on the workstation
String	ClientId	The Client ID of your own Autodesk app that needs authorization	Client ID of the default coolOrange Vault Integration app: dmPrAYr1c0AYJnIFzAA9ilEcJG5ClcJnUohC5PDcsnlXxhQH
String	ClientSecret	The Client Secret shown next to the Client ID is the password of your Autodesk app. Only required for Traditional Web App apps. Not used for Desktop, Mobile, Single-Page App types.	–
Uri	CallbackUrl	The redirect URL configured for your Autodesk app. During authorization, users are redirected to this URL in the browser. For localhost, the port and path must be free.	http://localhost:8080/

Return type

Bool:
$true ← on success.
$false ← on failure with an additional property ‘Error’ containing the Exception/ErrorMessage.

Remarks

To use this Cmdlet without parameters, it’s necessary to sign-in once with your Autodesk ID on workstations.
On first use, the signed-in user must grant consent to access APS endpoints and the user’s data.

After that, the session remains valid for a minimum of 15 days. During this period, your customizations can act on behalf of that user without requiring additional login or consent prompts. This applies both to client customizations and jobs.

The session is automatically refreshed in the background whenever an APS call is made, and a new Bearer token is provided by the global variable $APSConnection.Headers.
As long as the session is renewed regularly, the 15-day validity is automatically extended.

To persist the user session and reuse it in future Connect-APS calls, a Vault connection is required. Therefore, run Open-VaultConnection in your PowerShell IDE initially.

On the Job Processor, you can impersonate a user via the -User parameter, as long as that Autodesk ID has previously given consent.
This enables all APS calls in the job to execute in that user’s context without interaction. For security reasons, impersonation is only supported on the Job Processor.

The retrieved Three-Legged access token grants the following access scopes to the user’s account:

data:read data:write data:create data:search viewables:read
bucket:create bucket:read bucket:update bucket:delete
user-profile:read user:read user:write account:read account:write
code:all openid

For most integrations, the use of free APS endpoints is sufficient (see API Subscription Pilot). To access premium APIs, you must register your own Autodesk app and use the parameters -ClientId, -ClientSecret, and -CallbackUrl.

Note

Apps of type Desktop, Mobile, Single-Page App do not require a Client Secret but are limited in API access. Full access to all APIs requires a Traditional Web App type.

Make sure to store and use your Client Secret securely and in encrypted form.

Examples

Connect to APS on a workstation using the currently signed-in Autodesk ID and retrieve the 3-legged access token

Open-VaultConnection # First, open a Vault connection so the APS session can be reused if available
    
Connect-APS # Authenticates with APS using the signed-in Autodesk ID; a browser might open to complete the consent process

$global:APSConnection.Headers
<#
Name                           Value
----                           -----
Authorization                  Bearer eyJhbGciOiJSUzI1NiIsImapZCI6IoI4YjJkMzNhLSFlOTYtNDYwNS1iMWE4LTgwYjRhNWE4YjNlNyIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL2F1dG9kZXNrLmNvbSIsIm… 
#>

Run APS calls on Job Processor, impersonating the Autodesk ID of user who submitted the job

Connect-APS -User $job.SubmittedByAutodeskId # Authenticates with APS as the user who already granted consent on a workstation

$hub = $APSConnection.Hubs['build_MyCompany']
$response = Invoke-RestMethod -Method Get -Uri "https://developer.api.autodesk.com/project/v1/hubs/$($hub.id)/projects" -Headers $APSConnection.Headers

Prerequisite on workstation:

Register-VaultEvent -EventName LoginVault_Post -Action {
    
    Connect-APS # User must first authenticate using the signed-in Autodesk ID and consent via browser

    Add-VaultJob -Name '...'  -Parameters @{
        'SubmittedByAutodeskId' = $APSConnection.User # Submit the job, passing the Autodesk ID to impersonate
        'EntityId'= ...
        'EntityClassId'= ...
    } -Description "Job connecting to Autodesk Platform Services as Autodesk ID: $($APSConnection.User)" 
}

Error handling, analyze why the authentication failed

$result = Connect-APS -ClientId 'dmPrAYr1c0AYJnIFzAA9i...' -CallbackUrl 'http://localhost:6666/callback'
if(-not $result) {
   $result.Error # Returns "Authentication to Autodesk Platform Services failed! Please complete the browser sign-in using your Autodesk ID and grant all requested permissions to continue. Reason: ..."
}

# Alternatively, for jobs:

Connect-APS -User $job.SubmittedByAutodeskId -ErrorAction Stop
<#
Terminates with:
Job processing requires Autodesk Platform Services authentication! Please connect on your workstation using Autodesk ID '[email protected]' and grant consent.
#>