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:
- 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.
- Enable both the Identity API and Team Admin API.
For detailed instructions, see:
- Get Started — Register an app and request an access token.
- Get a three-legged token — Understand the OAuth authorization flow.
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:
teamcovers teams and team-level operations,team-userscovers users within a team, andteam-productscovers product pools and product assignments. - Permission:
readscopes allow your app to retrieve information, andwritescopes 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.
| Task | Accepted 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.
Recommended scopes
The scopes you request depend on what your app needs to do.
Example 1: Assign a product to a user
To complete the Assign a Product to a User walkthrough, request:
tmadmapi:team:read tmadmapi:team-users:write tmadmapi:team-products:write
Separate multiple scopes with spaces when you enter them in the Scope field in Postman or in the scope parameter of an OAuth token request.
These scopes allow your app to:
- Discover teams and retrieve the information needed for the walkthrough.
- Add users to a team.
- Assign products to users.
Example 2: Generate a read-only report
To retrieve team information, users, product pools, and assignments without making changes, request:
tmadmapi:team:read
This scope provides read access to teams and their associated data.
Troubleshoot authentication errors
If an API request fails with 401 or 403, use the following table to identify the likely cause.
| Status | Possible cause | Recommended 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
- Get Started — Register an app, obtain an access token, and list your teams.
- Product Pools and Assignments — Understand product assignments and seat counts.
- Error Handling — Learn how to interpret and handle API errors.