Request

Response

    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
    
    ConceptWhat it isOperations
    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:

    RoleWhat 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