Affinidi Meeting Place - Control Plane API

Affinidi Meeting Place - Control Plane API provides capabilities to enable the discovery of other participants to establish a connection and communicate securely. The Control Plane API enables participants to publish a connection offer that allows them to be discoverable and facilitates the creation of a secure communication channel with other participants.

The Control Plane API is built on Dart for a high-performance server, which provides optimal speed and stability for handling API requests.

Core Concepts

• Decentralised Identifier (DID) - A globally unique identifier that enables secure interactions. The DID is the cornerstone of Self-Sovereign Identity (SSI), a concept that aims to put individuals or entities in control of their digital identities.

• Out-Of-Band - The protocol defined in DIDComm enables sharing a DIDComm message or invitation through a transport method other than a direct, established DIDComm channel, such as via a QR code or a URL to create a new connection.

• Discovery - The Control Plane API allows participants to create connection offers or invitations that other parties can claim to initiate connection requests and establish a secure communication channel.

Key Features

• Discovery: Enables the discovery of other participants within the Meeting Place through published invitations, enhancing digital interactions.

• DID Authentication: Uses DID and DIDComm Message for secure authentication to generate an access token to call endpoints.

• Out-of-Band Invitation: Enable out-of-band communication to establish a connection between participants (e.g., individuals, businesses, and AI agents).

• Device Registration and Notification: Secure device registration ensures seamless delivery of notifications on key events, including push notifications on the user’s device.

• Group Chat: Provides group chat functionality, including management of members and sending messages to group members.

Get Started

Setup Guide

To deploy Control Plane API locally, follow this guide.

Working with Control Plane API

The Control Plane API requires an access token to call the endpoints. It uses a Decentralised Identifier (DID) and a DIDComm Message to authenticate users and generate the required token.

Authentication

The Control Plane API expects the Bearer Token to be present in the Authorization header of the request header. To obtain the token, a 2-step API request is required.

1. Make a POST /authenticate/challenge with your DID as the payload.

   
           
   POST /v1/authenticate/challenge
   
   {
      "did": "did:peer:...."
   }

   The endpoint returns a challenge string response required in the subsequent request as part of a DIDComm message using the challengeToken property and your DID.

   
           
   {
      "challenge": "string"
   }

   Sign the DIDComm message with the private key associated with your DID and encrypt it with the Control Plane API’s public key published through its DID, proving ownership of the DID used on Step 1.

2. After building the DIDComm message with a challenge string and encoding it with base64, call the /authenticate endpoint to obtain the token.

   
           
   POST /v1/authenticate
   
   {
      "challenge_response": "string"
   }

   The endpoint will return the access token, including the refresh token and duration of each token.

   
           
   {
      "access_token": "string",
      "access_expires_at": "string",
      "refresh_token": "string",
      "refresh_expires_at": "string"
   }

Use the access token in the Authorization header to call protected endpoints, such as device registration and publishing connection offers for discovery.

Refer to the authentication flow document for more details.

Calling Authenticated Endpoint

To call the authenticated API endpoints, use the DIDCommAuthToken generated from the /authenticate using DID and DIDComm Message.

Endpoint: POST /v1/check-offer-phrase Header: Auhorization: Bearer

Request application/json

        
{
  "offerPhrase": "ExistingOfferPhrase"
}

Response application/json

        
{
  "isInUse": true
}

API References

Refer to the list of available endpoints from the Control Plane API.