API Basics
This topic explains the four ideas behind the Team Admin API: teams, users, product pools, and assignments. It also covers how the API identifies each one. Read it first, so you know what each operation works on.
How the pieces fit together
A team holds users and product pools. An assignment gives one user a seat from one product pool.
Team
├── Users the people on the team, each with a role
└── Product pools the seats the team has for each product
└── Assignments the users who hold a seat from a pool
| Concept | What it is | Operations |
|---|---|---|
| Team | The place where your organization manages its users and their access to products. | List Teams |
| User | A person on a team. | List Team Users, Get Team User, Add Team User |
| Product pool | The seats a team has for a product. | List Product Pools |
| Assignment | A user's access to a product, using a seat from a pool. | List Assignments, Assign Product, Unassign Product |
Teams
A team is the place where an organization manages its users and their access to products. You manage the same teams and users in Autodesk Account. The Team Admin API lists the teams that you administer, and it doesn’t create or change teams. A team can also have hubs and projects, which the API doesn’t manage either.
The API only returns teams that you administer. You administer a team if you currently hold the primary administrator, secondary administrator, or SSO administrator role on it. The API checks the role on every request. For how access works, see Authentication and Permissions.
Users
A user is a person on a team. Most work with the API starts with a user, so find the person first, and then work out which product they need.
Each user has an id, a firstName and lastName, an email, a role, and an isEmailVerified indicator.
User roles
The role field tells you what the user can do on the team. Possible values:
| Role | What it means |
|---|---|
PRIMARY_ADMIN |
The primary administrator of the team. |
SECONDARY_ADMIN |
A secondary administrator of the team. |
SSO_ADMIN |
An administrator who is responsible for the team's single sign-on (SSO) configuration. |
USER |
A standard user of the team. |
EXTERNAL_USER |
A guest user who belongs to the team but is external to it. |
Read users
You can list the users of a team, find a user by an exact email address, and retrieve one user by ID.
The isEmailVerified field is an account-registration indicator. false means that account invitation or registration is pending, and true means that no pending invitation or registration is reported. It isn’t proof of email ownership, and it doesn’t show whether the user has accepted a team invitation.
Invite a user
You can invite a person to a team by email address. The team decides whether the new user is a USER or an EXTERNAL_USER, and an invited person might still need to accept the invitation. You can’t remove a user from a team through the API.
Product pools
A product pool is the set of seats that a team has for a product. A team can have several pools. Each pool has a productId and a productName. It reports its seats (totalQuantity, assignedQuantity, and unlimited) and the dates between which it is usable (startDate and endDate). The API returns only the supported pools whose seats you can assign to users.
Seat counts can be null, and they can change between the time you read a pool and the time you assign a product. For how to read them, see Product Pools and Assignments.
Assignments
An assignment gives a user access to a product, using a seat from a product pool. Each user and product pair appears once, and its assignmentType field (TEAM, DIRECT, or GROUP) shows how the user holds the product. You can create and remove DIRECT assignments only. The API returns inherited assignments when you list them, but you can’t create or remove them.
For the order in which the types apply and what each request returns, see Product Pools and Assignments.
IDs and base URL
The API identifies teams, users, and products with IDs. Treat every ID as opaque:
- Store and reuse the IDs that the API returns.
- Don’t parse, derive, or construct an ID.
- URL-encode an ID when you put it in a path or a query string.
Team IDs, user IDs, and product IDs aren’t interchangeable. Use the id that a List Teams response returns for a team, the id that a List Team Users response returns for a user, and the productId that a List Product Pools response returns for a product.
All requests go to the production server:
https://developer.api.autodesk.com/team-admin/v1
See also
- Authentication and Permissions — Learn who can call the API and which scopes each operation needs.
- Product Pools and Assignments — Learn how assignments and seat counts behave in detail.
- Pagination — Learn how to retrieve every page of a long list.
- Error Handling — Learn how to read and react to error responses.
- Rate Limits — Learn the request limits and how to stay within them.
- Get Started — Get a token and make your first request.