Invite a member to join a consortium

To invite another member to join a Quorum Blockchain Service (QBS) consortium, send an invite using the QBS management API, specifying the Azure subscription ID and email address of the party to be invited, and the role of the invited participant within the consortium (OWNER or MEMBER).

The invitee receives an email containing a personal invitation code to use when they provision their QBS member in Azure.

After the invitee provisions the QBS member using the code, QBS peers the inviter's and invitee's members together using an Azure VNet, enabling the two QBS members to securely communicate with one another and share the ledger.

Send an invite

To invite another member to join an existing consortium, use the POST method on the Invites endpoint of the API.

The URI of the Invites endpoint is:

Syntax

/subscriptions/{inviterSubscriptionId}/resourceGroups/{inviterResourceGroupName}/providers/ConsenSys.Blockchain/blockchainMembers/{inviterBlockchainMemberName}/invites

Example

/subscriptions/{inviterSubscriptionID}/resourceGroups/QbsContosoGroup/providers/ConsenSys.Blockchain/blockchainMembers/QbsContosoApp/invites

This endpoint requires the following parameters:

• {inviterSubscriptionId} - Subscription ID.
• {inviterResourceGroupName} - Resource group name.
• {inviterBlockchainMemberName} - Managed app name of the owner of the consortium to join.

The POST request body contains the invitee details:

• inviteeSubscriptionId - Azure Subscription ID of the member being invited to join the consortium.
• inviteeEmail - Email address of the member invited to join the consortium. It can't be the same as the inviter.
• inviteeRole - Role of the member invited to join the consortium (OWNER or MEMBER).
• expireInDays - Number of days before invite expires.
• inviterEmail - Your own email to get cc'd a copy of the invite. Use null to leave blank.

{
  "inviteeSubscriptionId": "{inviteeSubscriptionId}",
  "inviteeEmail": "member@fabrikham.com",
  "inviteeRole": "MEMBER",
  "expireInDays": 10,
  "inviterEmail": "member@contoso.com"
}

On successful completion of the request, the returned value in the response from the Invites endpoint contains the following information:

• inviteCode - The invitation code to use to join an existing consortium.
• inviterConsortium - The name of the consortium to join.
• inviterMember - The name of the member inviting to join their consortium. Technically, this is the name of the QBS managed app in Azure.
• inviteeSubscription - Azure subscription ID of the member invited to join the consortium.
• inviteeRole - Role of the member invited to join the consortium (OWNER or MEMBER).
• inviteeEmail - Email address of the member invited to join the consortium.

The response JSON payload has the following format:

{
  "inviteCode": "string",
  "inviterConsortium": "string",
  "inviterMember": "string",
  "inviteeSubscription": "string",
  "inviteeRole": "string",
  "inviteeEmail": "string",
  "inviterEmail": "string",
  "status": "string",
  "createdTimestamp": "string",
  "updatedTimestamp": "string",
  "expiryTimestamp": "string"
}

Try the API

You can execute the API method directly on the QBS management API website. First, authorize your access to the API by selecting Authorize at the top of the page.

In the dialog window with the available authorization methods, you can choose whether you want to authorize access to the API via an Azure Active Directory (AAD) account, or with a bearer token. Because you're interacting with the Swagger UI for the QBS API, we recommend authorizing via AAD. We recommend using a bearer token when you use the API programmatically.

Select Authorize for the AADToken option to authorize access to the API.

You're prompted to sign in with your corporate account. Enter the same credentials you use to sign into the Azure portal. Once completed, you're redirected to the authorization window. You can now close the dialog window and return to the API list.

Select Try out to test the API. The parameter fields unlock, allowing you to enter the required values.

You can find the required information in the Overview section of the QBS managed app in the Azure Portal.

• Inviter Subscription Id is the Subscription ID.
• Inviter Resource group of their Managed Application is the Resource group.
• Inviter Member name is the name of the managed app itself.

The following video demonstrates how to interact with the Swagger UI and send an invite.

Try the API programmatically

You can also use execute the API method programmatically. The following code snippets show examples of how to invoke the API in a variety of programming languages.

cURL

curl -X POST https://management.onquorum.net/subscriptions/{inviterSubscriptionId}/resourceGroups/QbsContosoGroup/providers/ConsenSys.Blockchain/blockchainMembers/QbsContosoApp/invites
-H 'Content-Type: application/json'
-d '{ "inviteeSubscriptionId": "{inviteeSubscriptionId}", "inviteeEmail": "member@fabrikham.com", "inviteeRole": "MEMBER", "expireInDays": 10, "inviterEmail": "member@contoso.com" }'

JavaScript

const subscriptionId = '{inviterSubscriptionId}';
const resourceGroup = 'QbsContosoGroup';
const appName = 'QbsContosoApp';

const inviteRequest = {
    inviterEmail = 'member@contoso.com', // inviter email address - or leave it null
    inviteeSubscriptionId = '{inviteeSubscriptionId}',  // Azure subscription ID of the invited member
    inviteeEmail = 'member@fabrikham.com', // email address of the invited member
    inviteeRole = 'MEMBER', // MEMBER or OWNER
    expireInDays = 10 // number of days of validity for this invite
};

async function createInvite() {
    const response = await fetch(
        `https://management.onquorum.net/subscriptions/${subscriptionId}/resourceGroups/${resourceGroup}/providers/ConsenSys.Blockchain/blockchainMembers/${appName}/invites`
        {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(inviteRequest)
        }
);

return response.json();
}

C#

HttpClient httpClient = new();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", bearerToken);

// https://www.nuget.org/packages/ConsenSys.QBS.Client
ConsenSys.QBS.QbsClient qbs = new(httpClient);

readonly Guid subscriptionId = Guid.Parse("{inviterSubscriptionId}");
readonly string resourceGroup = "QbsContosoGroup";
readonly string appName = "QbsContosoApp";

var inviteRequest = new InviteCreateRequestBody
{
    InviterEmail = "member@contoso.com", // inviter email address - or leave it null
    InviteeSubscriptionId = Guid.Parse("{inviteeSubscriptionId}"),  // Azure subscription ID of the invited member
    InviteeEmail = "member@fabrikham.com", // email address of the invited member
    InviteeRole = "MEMBER", // MEMBER or OWNER
    ExpireInDays = 10 // number of days of validity for this invite
};
var invite = await qbs.CreateInviteAsync(subscriptionId, resourceGroup, appName, inviteRequest);

Console.WriteLine($"Invite Code: {invite.InviteCode}");

Java

String subscriptionId = "ffd08efa-1f25-41b8-b4a1-0b7a5ec6fcd3";
String resourceGroup = "QbsContosoGroup";
String appName = "QbsContosoApp";

String endpoint = MessageFormat.format(
"https://management.onquorum.net/subscriptions/${0}/resourceGroups/${1}/providers/ConsenSys.Blockchain/blockchainMembers/${2}/invites",
subscriptionId, resourceGroup, appName);
URL url = new URL(endpoint);

HttpURLConnection http = (HttpURLConnection) url.openConnection();
http.setRequestMethod("POST");
http.setRequestProperty("Bearer", bearerToken);

http.setRequestProperty("Content-Type", "application/json");
http.setRequestProperty("Accept", "application/json");
http.setDoOutput(true);

String json = "{ "inviteeSubscriptionId": "{inviteeSubscriptionId}", "inviteeEmail": "member@fabrikham.com", "inviteeRole": "MEMBER", "expireInDays": 10, "inviterEmail": "member@contoso.com" }";
try (OutputStream os = con.getOutputStream()) {
    byte[] input = json.getBytes("utf-8");
    os.write(input, 0, input.length);
}

Python

import requests

subscriptionId = "ffd08efa-1f25-41b8-b4a1-0b7a5ec6fcd3"
resourceGroup = "QbsContosoGroup"
appName = "QbsContosoApp"

endpoint = "https://management.onquorum.net/subscriptions/{}/resourceGroups/{}/providers/ConsenSys.Blockchain/blockchainMembers/{}/invites"
message = requests.post(endpoint.format(subscriptionId, resourceGroup, appName, includeDeleted, includeRemoved), json={ "inviteeSubscriptionId": "{inviteeSubscriptionId}", "inviteeEmail": "member@fabrikham.com", "inviteeRole": "MEMBER", "expireInDays": 10, "inviterEmail": "member@contoso.com" })