Autodesk Platform Services Python client

A typed Python client and command-line interface for the Autodesk Platform Services (APS) APIs.

APS spans many services behind one host and one OAuth server. This package wraps them in an ergonomic, fully type-hinted client built on Pydantic models, plus an aps CLI for quick access from the terminal.

Features

• One client, every API - ten APS services mount as namespaces on a single client, from client.auth to client.tradetapp, sharing one connection pool and one token cache.
• Typed models - every response is parsed into Pydantic models with descriptive fields.
• Python client and CLI - use it as a library or straight from the shell via aps.
• Sync and async - Client and AsyncClient mount the same services under the same names over httpx.
• Both OAuth flows - 2-legged client credentials and the full 3-legged authorization code flow with PKCE.
• Sensible defaults - caches access tokens per scope set and refreshes them before they expire.
• The awkward parts handled - multipart uploads to signed S3 URLs, translation polling, URN encoding, JWT assertion signing, cursor paging, and the six different ways APS reports an error.

Services

Each APS API is mounted on the client as its own namespace.

Installation

pip install autodesk-platform-sdk
# or, with uv:
uv add autodesk-platform-sdk

Requires Python 3.12+.

Configuration

Credentials are read from environment variables (or can be passed directly to Client):

export APS_CLIENT_ID="your-client-id"
export APS_CLIENT_SECRET="your-client-secret"
export APS_CALLBACK_URL="http://localhost:53682/callback"

Create an app and its credentials at aps.autodesk.com/myapps. The client credentials grant needs an app registered as Server-to-Server or Traditional Web App; the 3-legged flow additionally needs the callback URL registered on that app, matched exactly - a trailing slash is a different URL.

Timeouts and retries

Every request carries a timeout (default (5, 30) seconds for connect and read) so a stalled connection can't hang the caller forever. Pass timeout= to override it (a single float, a (connect, read) tuple, or None to disable), and retries= to retry connection-establishment failures:

client = Client(timeout=60, retries=3)

retries retries only the connection stage, before any bytes reach the server, so a token is never minted twice. The CLI reads APS_API_TIMEOUT (seconds) and APS_API_RETRIES (count) for the same behavior.

Quick start

The application acts as itself

The 2-legged grant covers most of the platform. Tokens are cached per scope set and reused until they near expiry, so ask for one whenever you need it.

from autodesk_platform_sdk import Client
from autodesk_platform_sdk.services.oss.schemas import PolicyKey

client = Client()

bucket = client.oss.create_bucket("my-app-bucket", PolicyKey.transient)
client.oss.upload_object(bucket.bucket_key, "model.rvt", data)

Acting as a user

Most of APS is scoped to a person rather than an application, and BuildingConnected and TradeTapp accept nothing else. Install a 3-legged token once and every mounted service acts as that user.

from autodesk_platform_sdk import Scope

token = client.auth.authorize_interactively([Scope.data_read, Scope.openid])
client.auth.use_token(token)

client.data_management.list_hubs()  # would report no hubs without this
client.building_connected.list_projects()  # refuses a 2-legged token outright

For an unattended job, a saved refresh token is enough on its own - it is exchanged on first use and again whenever it expires. Refresh tokens are single-use, so persist the replacement:

client = Client(refresh_token=load())
client.auth.on_refresh = lambda token: save(token.refresh_token)

The awkward parts

Several APS workflows take three or four calls and a rule you have to know. Those are wrapped in one method each, so upload_object runs the whole signed-S3 flow with automatic multipart splitting, and wait_for_translation polls to completion:

import pathlib

from autodesk_platform_sdk.services.modelderivative.schemas import OutputType

uploaded = client.oss.upload_object(
    bucket_key, "tower.rvt", pathlib.Path("tower.rvt").read_bytes()
)

client.model_derivative.translate(uploaded.object_id, [OutputType.svf2])
manifest = client.model_derivative.wait_for_translation(uploaded.object_id)
assert manifest.is_successful()

AsyncClient mirrors Client method for method - same arguments, same return types, awaited.

Each service's docstring carries what is peculiar to it: which calls need a subscription, where an empty listing means a permissions failure rather than no data, which IDs carry a b. prefix. Read it in your editor, or with help(client.data_management).

CLI

Every service is a command group. Connection settings come from the same APS_* variables.

aps auth login --scope data:read          # 3-legged, opens a browser
aps oss buckets
aps derivative translate <urn> --output svf2
aps bc projects --include-closed

aps --help lists the groups; aps <group> --help lists its commands.

Reference Documentation

• APS documentation
• Authentication (OAuth) v2
• OAuth scopes
• Secure Service Account v1
• Data Management and Object Storage v2
• Model Derivative v2
• Webhooks v1
• ACC Account Admin v1
• ACC Issues v1
• BuildingConnected v2/v3
• TradeTapp v2
• Official OpenAPI specifications

API reference

Authentication (client.auth)

Service accounts (client.service_accounts)

Object storage (client.oss)

Model Derivative (client.model_derivative)

Data Management (client.data_management)

BuildingConnected (client.building_connected)

TradeTapp (client.tradetapp)

Webhooks (client.webhooks)

ACC Account Admin (client.account_admin)

ACC Issues (client.issues)