User Invitation API overview
The Cloud Identity User Invitation API allows you to identify and manage unmanaged accounts as part of onboarding users to your Google Workspace or Cloud Identity domain.
Unmanaged accounts are defined by the following criteria:
- the email address is a consumer account and it's the primary email address of the account, and
- the domain of the email address matches an existing verified Google Workspace or Cloud Identity domain
These accounts generally exist because one of the customer's users has signed up for consumer Google services using their work or educational email address. When the customer then signs up for Google Workspace or Cloud Identity and provisions a user account with the same primary email address as an existing unmanaged account, that unmanaged account becomes conflicted and needs to be resolved.
The User Invitation API makes key resolution tasks automatable:
- Determine if a given email address is eligible to join the customer's domain (must meet both criteria)
- Send ad-hoc or batch email invitations to eligible email addresses so they can join the customer's domain
- Retrieve a list of unmanaged accounts, filterable by their invitation
state. All unmanaged accounts on the customer's domain are treated as
unsent user invitations (
state==NOT_YET_SENT) until they are sent.
- Look up a specific invitation by email address
- Cancel already-sent invitations
The user invitation flow allows both the end user and the administrator to ensure that any data created using the consumer account is managed by the correct entity:
- If the end user has business-related data under the consumer account and accepts the invitation, the administrator can take ownership and manage the data according to the customer's policies.
- If the end user's data is not business-related and they decline, the invitation gives the user notice that they may need to rename the email address later if the admin creates a new Google account for them. The administrator can create a new managed account and evict the primary email address of the consumer account, creating the conflict. The end user will then be asked to rename their email address to another email address every time they log in to their personal Google account.
Here are a few next steps you might take:
- To set up the API, refer to Setting up the User Invitation API.
- To understand how account conflict resolution works in the Admin Console, read Find and manage existing accounts in the Google Admin Help Center.