User and account management

User and account management APIs (also known as Identity and Access Management (IAM)) help you manage your marketplace users and companies.They enable you to manage users, companies, and memberships in your marketplace. You can also use them to create marketplace companies, add users to the companies (which creates company memberships), and manage user roles, which determine user permissions in different companies.

GraphQL APIs use the term "Account" instead of "Company". Companies are called Accounts, and Company Memberships are called Account Memberships.

There are three components that are integral to these APIs: companies (or accounts), users, and company memberships.

Data model

The following diagram illustrates the data model for users and accounts and the flow of information between the components.

Component	Description
Companies	All users must be part of at least one company (or account), and every new company requires at least one user whose details you must provide when it is created. Each company has a unique identifier, which is required in many requests, such as adding users, creating payment instruments, and creating subscriptions. It is not possible to delete companies. However, you can disable them, which prevents all users from logging in.
Users	The user record contains basic information about the user, such as name, address, and email. Any role or permission information is associated with the company membership. Users must be associated with at least one company. You cannot delete a user directly using an API. Instead, to delete a user, you must delete their last company membership.
Managed users	Most users must log in to a marketplace to access their products and perform various tasks, depending on their role. However, sometimes, a user might not even know about the marketplace and does not need to log in. For example, when Resellers sell products directly to end users, those users only need access to the products they purchased. Users who do not require login access are managed users. They do not receive account activation emails or other direct communications from the marketplace. The managed user type exists for users who have actions performed on their behalf but do not interact with the marketplace themselves.
Company memberships	The company (or account) membership is the central element in the IAM data model. It links users and companies. Roles are defined at the company membership level: users can belong to multiple companies but have different permissions depending on the roles associated with each company membership.You can delete company memberships, but you must first remove all references to the membership (from product assignments, product ownership, and so on).
Roles	Most roles are associated with the company membership and determine the user's permissions in each company. It is possible for users to be members of different companies and have different roles in each (Marketplace Manager in one, Developer in another, and so on), even if the companies are in the same marketplace.
Groups	Groups are collections of users within companies that Company Administrators can use to simplify specific tasks. For example, they can assign applications to groups instead of individual users. Groups belong to particular companies, so only users of the corresponding companies can be group members.
Invitations	Invitations represent pending company memberships that recipient users still need to activate. When a user accepts an invitation, a membership and a user account are created in the specified company.

Active and enabled users, companies, and memberships

Users and companies can be active or inactive, and companies and company memberships can be enabled or disabled. In the API, the company object contains an enabled boolean value and a status enum, which can be ACTIVE or INACTIVE. You can enable or disable companies through the Update company request but cannot change the activation status. Although similar, these terms indicate different things about users or companies.

• For companies:
  • The activation status indicates whether the first user of a company has clicked the link in the activation email automatically sent to them by the marketplace. When a user clicks the link, the company (and user) becomes ACTIVE.
  • The enabled boolean determines whether users can log in to companies. Companies are enabled by default. If you disable a company, no users can log in to the company. If you disable a user, the user can no longer log in.
• For users:
  • The activation status indicates whether a user has accepted their email invitation to the company. All users are INACTIVE by default and become ACTIVE when accepting invitations.
  • Users themselves cannot be enabled or disabled. Instead, the company membershipenabled boolean determines whether the user can log in to the related company. Memberships are enabled by default. If you disable a membership, the user associated with the membership can no longer log in to the affiliated company.