Discovering Work

An agent can receive various requests which require a human response by the agent's owner. These requests consist of the following types of inbound work which can be received by an agent:

Type	Description
Inbound Connection Offer	Someone wants to establish a relationship with you using an invitation in which 'manual_accept' is set to true.
Inbound Credential Request	You are an issuer and a holder (i.e. end user) wants you to issue a credential to them.
Inbound Credential Offer	You are a holder (i.e. end user) and someone is offering a credential to you.
Inbound Verification Request	You are a verifier and a prover (i.e. end user) wants you to verify a proof.
Inbound Proof Request	You are a prover (i.e. end user) and a verifier wants you to prove something.

The agent's owner can either approve or reject each of these types of inbound work.

Retrieving Inbound Work

The following returns all of the 5 types of inbound work for an agent. In other words, it returns everything that may require human review and response which is associated with the agent.

$ curl -u $USER1 $URL/api/v1/waiters
{
  "connections": {
    "offers": {
      "count": 0,
      "items": []
    }
  },
  "credentials": {
    "offers": {
      "count": 0,
      "items": []
    },
    "requests": {
      "count": 0,
      "items": []
    }
  },
  "verifications": {
    "proof_requests": {
      "count": 0,
      "items": []
    },
    "verifications_requests": {
      "count": 0,
      "items": []
    }
  }
}

The value of each item returned is the same as that returned when listing a connection, credential, or verification, respectively.

Listeners for Inbound Work Notifications

Instead of polling the /api/v1/waiters endpoint, you can also register one or more listeners to be notified when work is available. The current list of notifications that a listener may receive includes:

Type	Description
Inbound Connection Offer	Someone wants to establish a relationship with you using an invitation in which 'manual_accept' is set to true.
Inbound Credential Request	You are an issuer and a holder (i.e. end user) wants you to issue a credential to them.
Inbound Credential Offer	You are a holder (i.e. end user) and someone is offering a credential to you.
Inbound Verification Request	You are a verifier and a prover (i.e. end user) wants you to verify a proof.
Inbound Proof Request	You are a prover (i.e. end user) and a verifier wants you to prove something.
Inbound Proof Presentation	You are a verifier and a prover has presented you with a proof response which has completed the default verification process and its final state (passed or failed) has been determined.
Inbound Ack Message	You are a prover and the verifier is letting you know whether the verification on your proof response has passed or failed.
Verification Problem Encountered	You are a prover or a verifier. The other end of a proof request has deleted the request before the verification process was complete.
Inbound Basic Message	One of the agents with which you have a relationship sent you a message.

Notifying a web application

To add a REST listener which is listening at the https://myhost/notifications endpoint:

curl -u $USER1 -X POST -d '{"rest": {"url": "https://myhost/notifications"}}' $URL/api/v1/listeners -H 'Content-Type: application/json'

The body of the POST which will then be sent to the REST endpoint for various notifications is of the following form:

{
  'type': '<connections> | <credentials> | <verifications> | <messages>',
  'id': '<id>',
  'state': '<state>',
  'message': '<concise message>',
  'timestamp': <time-of-event>,
  'object': {
    <the complete object>
  }
}

where:

• type specifies the type of object related to the notification (connections, credentials, verifications, or messages),
• id is the unique identitier of the object,
• state is the new state of the object,
• message is a concise one-line message describing the event, and
• timestamp is the time of the event in milliseconds.

Notifying a mobile application

Configure your favorite push notification server to work with a listener.

Alternately, you can use the IBM Cloud Push Notification Service.

Viewing listeners

Issuer1 lists all listeners as follows:

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

To list a specific listener where <listener-id> is the id field of the listener as returned by the previous call.

curl -u $ISSUER1 $URL/api/v1/listeners/<listener-id>

Deleting listeners

Issuer1 deletes a listener where <listener-id> is the id field of the listener to be deleted:

curl -u $ISSUER1 -X DELETE $URL/api/v1/listeners/<listener-id>

Next, let's continue with a brief note on basic messages.