App Invites Proxy API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Invite a collaborator to an app

A developer tool can invite a teammate to help manage an existing app. Access is granted when the teammate accepts, not when the invitation is created.

Prerequisites

• Obtain the app ID from the Apps API.
• Prepare a signed-in user with account context for invitation creation.
• Obtain Identity role IDs applicable to app access. Use Get Roles Info with its required account-level API key, selecting the relevant id values from predefinedRoles or customRoles, or use configured app-access role IDs. Don't substitute unrelated site roles.

To invite a collaborator and verify acceptance:

1. Call Get App Contributors Proxy with appId. Check both contributors and invites for the recipient. Continue this flow for a recipient without existing access or an active invitation. An active invitation for the same app and email prevents creating another one.

2. Call Create App Invite Proxy with invite.appId, invite.destEmail, and invite.policyIds. The service emails the recipient. Save the returned invite.id; invite.inviteData contains the invitation details and invite.acceptLink is the recipient's acceptance link. Treat email addresses and acceptance links as sensitive data.

3. Have the recipient follow the acceptance link and accept the invitation while signed in.

4. Call Get App Contributors Proxy again to inspect the invitation status and current contributors. Don't treat successful invitation creation as proof that access has been granted.

Resend an app invitation

A teammate may need another invitation email after the original was misplaced, declined, or expired.

To renew and resend the invitation:

1. Call Get App Contributors Proxy with appId and select the pending, declined, or expired invitation from invites. Used or deleted invitations can't be reset.
2. Call Reset App Invite Proxy with the selected invitation's id as inviteId. This renews its expiration and sends another email. Store the updated invitation and acceptance link returned in invite.
3. After the recipient accepts, call Get App Contributors Proxy to verify the invitation status and assigned access.

Cancel an unused app invitation

An invitation sent in error should no longer be usable. Cancelling it doesn't remove roles already assigned to a collaborator.

To cancel the invitation:

1. Call Get App Contributors Proxy with appId and select the pending or expired invitation from invites.
2. Call Delete App Invite Proxy with the selected invitation's id as inviteId. The invitation is marked deleted.
3. Call Get App Contributors Proxy again to verify that the invitation is no longer active.

Remove a collaborator's app access

When a teammate leaves a project, remove their assigned access and cancel any outstanding invitations that could grant access again. The app owner's account can't be removed with this API.

To remove a collaborator's access:

1. Call Get App Contributors Proxy with appId. Select the contributor's account ID from contributors[].metaData.id, not their user ID from contributors[].id, and identify their pending or expired invitations in invites.
2. Call Clear Assigned App Policies Proxy with this accountId and the appId. The response lists the removed assignment IDs. This doesn't delete the account or app.
3. For each outstanding invitation identified in step 1, call Delete App Invite Proxy with its id as inviteId. Removing role assignments alone doesn't cancel invitations.
4. Call Get App Contributors Proxy again to verify that the assigned access and outstanding invitations have been removed or cancelled.