Managing Invitations

In order for two agents to communicate, one agent must create an invitation and share it with the other agent. The agent which creates the invitation is called the inviter and the other agent is called the invitee.

The way in which the inviter shares the invitation with the invitee is not defined by IBM Verify Credentials. It may be via email, QRCode, or by any other means. This invitation is referred to as an out of band invitation because the invitation message does not flow over a DID comm channel, but instead via an undefined out-of-band communication channel.

Just as we receive multiple types of invitations in the mail (e.g. wedding invitations, invitations to receive a credit card, etc), so there are multiple types of IBM Verify Credential invitations:

  1. connection invitation - an invitation to connect with no other specific intent provided;
  2. issuance invitation - an invitation to begin an issuance interaction (with an optional request to connect first);
  3. verification invitation - an invitation to begin a verification interaction (with an optional request to connect first).

Creating an invitation

This section describes how to create an connection invitation. Creating issuance and verification invitations are described later in the Issue Credentials and Verify Proofs sections, respectively.

Issuer1 creates a connection invitation as follows. This invitation has no limit on the number of times that it may be accepted.

curl -u $ISSUER1 -X POST -d '{}' $URL/api/v1/invitations -H "Content-Type: application/json"

Or the following creates a connection invitation which can only be accepted once.

curl -u $ISSUER1 -X POST -d '{"max_acceptances":1}' $URL/api/v1/invitations -H "Content-Type: application/json"

In both cases, the body of the response contains a short_url field which is referred to below as the <short-invitation-url>.

More generally, the following table defines all of the possible options which may be passed in the body of the POST /api/v1/invitations call in order to control the type and operational characteristics of the invitation:

Argument Default Value Description
goal None A human-readable description for the purpose or goal of the invitation
goal_code None A machine-readable code indicating the goal of the invitation. For example, issue-vc to issue a credential and request-proof to verify a proof.
manual_accept false If true, the inviter must manually accept all connection offers received via this invitation; otherwise, the inviter's agent will automatically accept any such connection offer.
max_acceptances -1 If >= 0, this is the maximum number of times that this invitation may be accepted; otherwise, there is no limit. An invitation can be deleted at any time in order to prevent any future acceptances from being possible.
max_connections None If set, this is the maximum number of connections created from this invitation which can concurrently exist; otherwise, there is no limit.
max_queue_count None If set, any edge agent which connects to a mediator using this invitation will be limited to queueing this many messages. Any messages received by the mediator which would exceed this limit are discarded by the mediator.
invitation_lifetime_ms None If set, this is the number of milliseconds that the invitation may be used before it expires; otherwise, the invitation does not expire.
connection_lifetime_ms None If set, this is the number of milliseconds that any connection created from this invitation may be used before the connection expires; otherwise, connections created from this invitation do not expire.
direct_route true If true, messages are sent directly to the inviter; otherwise, messages destined for the inviter are proxied through the agency in order to thrwart attempts to gather information through traffic analysis.
properties {} Properties which are set on the connection and associated with the inviter. Properties provided by the inviter when manually accepting a connection offer are also set on the connection and associated with the inviter. If a property is in both the invitation and a manual acceptance property, the value of the manual acceptance property takes precedence.
attach.cred_offer None An issuer wants to issue a credential to a holder
attach.cred_proposal None A holder wants an issuer to issue a credential
attach.verification_request None A verifier wants a holder to prove something
attach.verification_proposal None A holder wants to prove something to a verifier
attach.recipient None The recipient of the attachment; one of inviter or invitee
attach.use_connection None If true, connect first or reuse an existing connection; otherwise, initiate a connection-less interaction

If no attach section is specified, the invitation is an invitation to connect only.

If the attach section is specified:

  • exactly one of the following fields must be specified: attach.cred_offer, attach.cred_proposal, attach.verification_request, or attach.verification_proposal. The first two begin an issuance interaction and the later two begin a verification interaction.
  • both attach.recipient and attach.use_connection are required fields.

Accepting an invitation

No matter what type of invitation is created (connection, issuance, or verification), the invitation is accepted in the same way, by passing the <short-invitation-url> to the invitation processor as follows:

curl -u $USER1 -X PUT -d '{"url": "<short-invitation-url>"}' $URL/api/v1/invitation_processor -H "Content-Type: application/json"

Issuer1 and user1 should now be connected. We will talk more about managing connections later.

Listing invitations

The following command lists the invitations for issuer1.

curl -u $ISSUER1 $URL/api/v1/invitations

Or to get a specific invitation by id, where <invitation-id> is the unique ID of the invitation.

curl -u $ISSUER1 $URL/api/v1/invitations/<invitation-id>

Deleting Invitations

You may want to delete an invitation because you no longer want to allow it to be used.

The following will delete the invitation.

curl -u $USER1 -X DELETE $URL/api/v1/invitations/<invitation-id>

Next, let's look at managing connections for long-term communication between agents.