Creating and managing user invitations

This page explains how to perform some fundamental operations with the Cloud Identity User Invitation API.

Before you begin

Note: Before you use any of the Cloud Identity APIs, you must set up Cloud Identity. See Setting up Cloud Identity for instructions.

Perform the following tasks before proceeding with the information on this page:

Determining invitation eligibility

As noted in the overview, to be invited a user account must meet multiple criteria. You can use the IsInvitableUser() method to find out if a given user account is eligible.

REST

To check the eligibility of a user account, call customers.userinvitations.isInvitableUser() with the customer ID and the account's email address.

Sample request

GET https://cloudidentity.googleapis.com/v1/customers/C00000000/userinvitations/writer@altostrat.com:isInvitableUser

Retrieving user invitations

The User Invitation API provides methods for retrieving a single user invitation and retrieving all of them. When retrieving all user invitations, you can optionally filter them by state and set the sorting order.

Retrieving a single user invitation

REST

To retrieve a single user invitation, call customers.userinvitations.get() with the customer ID and the account's email address.

Sample request

GET https://cloudidentity.googleapis.com/v1/customers/C00000000/userinvitations/writer@altostrat.com

Retrieving a list of user invitations

All unmanaged users appear automatically as invitations in the NOT_YET_SENT state until otherwise acted upon by either the admin or the end user. Once an invitation is accepted by the user, the account is no longer considered unmanaged.

You can check for multiple states by adding an or operator in the filter: state=='accepted'||state=='declined'

REST

To retrieve a list of user invitations, call customers.userinvitations.list() with the customer ID and any desired query parameters to filter, order, and paginate the results. The following example returns a list of all unmanaged users, ordered by the last updated time in descending order.

Sample request

GET https://cloudidentity.googleapis.com/v1/customers/C00000000/userinvitations?filter=state!='accepted'&orderBy='updateTime desc'

Sending user invitations

User invitations are not automatically sent to eligible users. Once you have a list of the users you want to invite, you can use the customers.userinvitations.send() method. This will also create an invitation if it doesn't exist.

REST

To send a user invitation email to a user, call customers.userinvitations.send() with the customer ID and the user account's email address.

Sample request

POST https://cloudidentity.googleapis.com/v1/customers/C00000000/userinvitations/writer@altostrat.com:send

Canceling user invitations

User invitations can be canceled until they are either accepted or declined. Call the customers.userinvitations.cancel() method to cancel an invitation.

REST

To cancel a user invitation, call customers.userinvitations.cancel() with the customer ID and the user account's email address.

Sample request

POST https://cloudidentity.googleapis.com/v1/customers/C00000000/userinvitations/writer@altostrat.com:cancel