New-MgInvitation

Reference

Module:: Microsoft.Graph.Identity.SignIns

Use this API to create a new invitation or reset the redemption status for a guest user who already redeemed their invitation. Invitation adds an external user to the organization. When creating a new invitation, you have several options available:

Note

To view the beta release of this cmdlet, view New-MgBetaInvitation

Syntax

New-MgInvitation
   [-ResponseHeadersVariable <String>]
   [-AdditionalProperties <Hashtable>]
   [-Id <String>]
   [-InviteRedeemUrl <String>]
   [-InviteRedirectUrl <String>]
   [-InvitedUser <IMicrosoftGraphUser>]
   [-InvitedUserDisplayName <String>]
   [-InvitedUserEmailAddress <String>]
   [-InvitedUserMessageInfo <IMicrosoftGraphInvitedUserMessageInfo>]
   [-InvitedUserSponsors <IMicrosoftGraphDirectoryObject[]>]
   [-InvitedUserType <String>]
   [-ResetRedemption]
   [-SendInvitationMessage]
   [-Status <String>]
   [-Headers <IDictionary>]
   [-ProgressAction <ActionPreference>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-MgInvitation
   -BodyParameter <IMicrosoftGraphInvitation>
   [-ResponseHeadersVariable <String>]
   [-Headers <IDictionary>]
   [-ProgressAction <ActionPreference>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

Permissions

Permission type	Least privileged permissions	Higher privileged permissions
Delegated (work or school account)	User.Invite.All	Directory.ReadWrite.All, User.ReadWrite.All
Delegated (personal Microsoft account)	Not supported.	Not supported.
Application	User.Invite.All	Directory.ReadWrite.All, User.ReadWrite.All

Examples

Example 1: Invite a user and send default invitation email

PS C:\> New-MgInvitation -InvitedUserDisplayName "John Doe" -InvitedUserEmailAddress John@contoso.com -InviteRedirectUrl "https://myapplications.microsoft.com" -SendInvitationMessage:$true

Id                                   InviteRedeemUrl                                                                                                   
--                                   ---------------                                                                                                   
e4247160-a778-428a-8218-bcaf717870dd https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%2f%3ftenant%3d094a...

Invite a guest user with the following:

Display name is John Doe
Invited email is John@contoso.com
Once the user redeems the invitation, the user will be redirected to https://myapplications.microsoft.com
The standard invitation email will be sent to the specified email

Example 2: Invite a user and set usertype to member

PS C:\> New-MgInvitation -InvitedUserDisplayName "John Doe" -InvitedUserEmailAddress John@contoso.com -InviteRedirectUrl "https://myapplications.microsoft.com" -InvitedUserType Member

Id                                   InviteRedeemUrl                                                                                                   
--                                   ---------------                                                                                                   
2fe815c1-aecc-4f66-b1d0-952a60df2409 https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%2f%3ftenant%3d094a...

Invite a guest user with the following:

Display name is John Doe
Invited email is John@contoso.com
Once the user redeems the invitation, the user will be redirected to https://myapplications.microsoft.com
The usertype will be set to Member
SendInvitationMessage is not specified so by default an invitation email will NOT be sent

Parameters

-AdditionalProperties

Additional Parameters

Type:	Hashtable
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-BodyParameter

invitation To construct, see NOTES section for BODYPARAMETER properties and create a hash table.

Type:	IMicrosoftGraphInvitation
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type:	SwitchParameter
Aliases:	cf
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Headers

Optional headers that will be added to the request.

Type:	IDictionary
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-Id

The unique identifier for an entity. Read-only.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InvitedUser

user To construct, see NOTES section for INVITEDUSER properties and create a hash table.

Type:	IMicrosoftGraphUser
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InvitedUserDisplayName

The display name of the user being invited.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InvitedUserEmailAddress

The email address of the user being invited. Required. The following special characters aren't permitted in the email address:Tilde (~)Exclamation point (!)Number sign (#)Dollar sign ($)Percent (%)Circumflex (^)Ampersand (&)Asterisk (*)Parentheses (( ))Plus sign (+)Equal sign (=)Brackets ([ ])Braces ({ })Backslash (/)Slash mark (/)Pipe (/|)Semicolon (;)Colon (:)Quotation marks (')Angle brackets (< >)Question mark ()Comma (,)However, the following exceptions apply:A period (.) or a hyphen (-) is permitted anywhere in the user name, except at the beginning or end of the name.An underscore (_) is permitted anywhere in the user name, including at the beginning or end of the name.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InvitedUserMessageInfo

invitedUserMessageInfo To construct, see NOTES section for INVITEDUSERMESSAGEINFO properties and create a hash table.

Type:	IMicrosoftGraphInvitedUserMessageInfo
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InvitedUserSponsors

The users or groups who are sponsors of the invited user. Sponsors are users and groups that are responsible for guest users' privileges in the tenant and for keeping the guest users' information and access up to date. To construct, see NOTES section for INVITEDUSERSPONSORS properties and create a hash table.

Type:	IMicrosoftGraphDirectoryObject[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InvitedUserType

The userType of the user being invited. By default, this is Guest. You can invite as Member if you're a company administrator.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InviteRedeemUrl

The URL the user can use to redeem their invitation. Read-only.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InviteRedirectUrl

The URL the user should be redirected to after the invitation is redeemed. Required.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ProgressAction

Type:	ActionPreference
Aliases:	proga
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ResetRedemption

Reset the user's redemption status and reinvite a user while retaining their user identifier, group memberships, and app assignments. This property allows you to enable a user to sign-in using a different email address from the one in the previous invitation. When true, the invitedUser/id relationship is required. For more information about using this property, see Reset redemption status for a guest user.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ResponseHeadersVariable

Optional Response Headers Variable.

Type:	String
Aliases:	RHV
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SendInvitationMessage

Indicates whether an email should be sent to the user being invited. The default is false.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Status

The status of the invitation. Possible values are: PendingAcceptance, Completed, InProgress, and Error.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type:	SwitchParameter
Aliases:	wi
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Inputs

Microsoft.Graph.PowerShell.Models.IMicrosoftGraphInvitation

System.Collections.IDictionary

Outputs