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:
- Read the User Invitation API overview.
- Set up the User Invitation API.
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.
- If you call
customers.userinvitations.list()with the state in the request, it will return only users whose invitation is in that state. - If you call
customers.userinvitations.list()without the state in the request, it will return all user invitations.
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