Acquire an access token with the User.Invite.All permission using a service principal or a delegated account holding at least the Guest Inviter role.
POST to https://graph.microsoft.com/v1.0/invitations with a body containing invitedUserEmailAddress, inviteRedirectUrl, and sendInvitationMessage set to true or false depending on whether you want Entra to send the email.
The response contains an invitedUser object with the newly created guest user's id and an inviteRedeemUrl; store the user id for subsequent role and group assignments.
Assign the guest to the appropriate groups or app roles by calling POST /v1.0/groups/{groupId}/members/$ref with the guest user's id.
Poll the user's externalUserState property (GET /v1.0/users/{userId}?$select=externalUserState) to check whether the invitation has been redeemed.
Handle guest user redemption changes: as of the 2025 rollout, guests are redirected to their home tenant sign-in page rather than a generic Microsoft page, which affects any redemption flow instructions you provide.
Known gotchas
Invitations can only be sent to external email addresses; attempting to invite an address already registered in the tenant returns a 400 error.
The inviteRedeemUrl is single-use and expires; if the guest does not redeem it, you must reset the redemption status via the invitation API before they can redeem again.
Guest users are created in a pending state (externalUserState = PendingAcceptance) and cannot access resources until redemption completes; do not grant permissions and expect immediate access.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp