Request

Response

    Authentication and Permissions

    The Team Admin API uses three-legged OAuth authentication to act on behalf of a team administrator. This topic explains who can use the API, how to configure your app, which scopes to request, and how to troubleshoot authentication errors.

    Who can use the API?

    Every Team Admin API request requires a three-legged access token authorized by a person who currently administers the target team.

    The person must have one of these roles:

    • Primary administrator
    • Secondary administrator
    • SSO administrator

    The API checks administrator permissions on every request. If a person loses their administrator role, their requests fail even if their access token is still valid.

    Note: The API returns the same 403 response when a team doesn’t exist and when the caller doesn’t administer it. This prevents unauthorized callers from discovering whether a team exists.

    Unsupported authentication methods

    The Team Admin API doesn’t support:

    • Two-legged access tokens: Application-only authentication isn’t accepted.
    • Service accounts: Currently, service accounts can’t act as API callers.

    Your app must use a three-legged access token authorized by a team administrator.

    Configure your app

    Before requesting an access token, register your app on the APS portal.

    When registering:

    1. Select Traditional Web App as the app type. Currently, it is the only supported app type. Other app types, including Server-to-Server, aren’t supported.
    2. Enable both the Identity API and Team Admin API.

    For detailed instructions, see:

    Send the access token

    Request your access token from the APS production server:

    https://developer.api.autodesk.com

    Use the same server for Team Admin API requests.

    Include the token in the Authorization header of every request:

    Authorization: Bearer <YOUR_ACCESS_TOKEN>
    

    Understand API scopes

    Scopes determine which operations your app can perform. When requesting an access token, your app asks the administrator to authorize specific scopes. Each operation accepts one or more scopes, and any one of them is sufficient. You don’t need every scope listed for an operation.

    Scope names

    Scope names follow the pattern tmadmapi:<category>:<permission>:

    • Category: team covers teams and team-level operations, team-users covers users within a team, and team-products covers product pools and product assignments.
    • Permission: read scopes allow your app to retrieve information, and write scopes allow it to make changes.

    Note: Write scopes don’t automatically grant read access. If your app needs to retrieve IDs, inspect existing data, or verify changes, request the appropriate read scopes as well.

    Scopes required for each operation

    The following table lists the accepted scopes for each operation, grouped by task.

    TaskAccepted scopes
    List teams you administer tmadmapi:team:read
    List or retrieve team users tmadmapi:team-users:read or tmadmapi:team:read
    Add a user to a team tmadmapi:team-users:write or tmadmapi:team:write
    List product pools or assignments tmadmapi:team-products:read or tmadmapi:team:read
    Assign or unassign a product tmadmapi:team-products:write

    Note: Listing teams requires tmadmapi:team:read. No other scope is accepted for this operation. If your app needs to discover team IDs before performing other operations, include this scope.

    For operation-specific requirements, see the REST API Reference.

    Troubleshoot authentication errors

    If an API request fails with 401 or 403, use the following table to identify the likely cause.

    StatusPossible causeRecommended action
    401 The access token is missing, invalid, or expired. Confirm that the request includes the Authorization header with the Bearer scheme and a valid token. If the token is expired or invalid, get a new access token and send the request again.
    403 The token lacks an accepted scope, or the caller doesn't administer the target team. Check that the token includes at least one scope that the operation accepts, that the person who authorized it currently administers the team, and that the team ID is correct.

    For instructions on refreshing an expired token in Postman, see Get Started. For additional error codes and responses, see Error Handling.

    See also