Skip to main content
API docs by Redocly

Enterprise Services OpenAPI specification (0.7.5)

Download OpenAPI specification:Download

The Enterprise Services OpenAPI specification defines a suite of products complementing the basic services provided by the Prism Agent. The Enterprise Services suite currently includes two products: Onboard and Authenticate.

The Onboard product allows organizations to request and obtain a Decentralized Identifier (DID) from another party.

Getting a DID flow:

  • The inviting party creates a DID request.
  • The DID request is encoded, typically as a QR code or deep link, and sent to the other party via an appropriate channel.
  • The receiving party uses their wallet to scan/receive the DID request.
  • The wallet creates a new DID and sends it back to the onboardEndpoint, specified in the DID request.
  • The inviting party associates the received DID with its system context, for example, with a userId.

The Authenticate product facilitates the authentication of users and devices through decentralized identifiers (DIDs) they control. Provided API streamlines the process of creating and managing authentication challenges, sent to parties for authentication.

Authentication flow:

  • A new authentication challenge is created.
  • The challenge is encoded and sent to the relevant party through the appropriate communication channel based on the use-case.
  • The receiving party signs the nonce from challenge and sends both the signature and did fields to the submissionEndpoint for verification.
  • The signature is verified, and the challenge state is updated accordingly.
  • Application can then evaluate the validity of the submitted signature, check if the used DID is recognized, and take appropriate follow-up actions.

ADDITIONAL NOTES:

The authentication challenge session has a limited time frame and a defined expiration time.

For the time being, wallets can only use did:peer DIDs. did:prism support is on its way.

Onboard

Create DID requests and track their state to act upon received DIDs

Create a new DID request

Creates a new DID request and the corresponding state to track the request by ID. The request may include an optional from parameter that enables wallets to indicate the sender of the challenge.

The created DID request state record contains a didRequest field, which should be encoded and delivered to the recipient, typically in the form of a QR code. Upon receiving the DID for the created request, the state record will be updated. The initial state is set to pending, and upon receiving a valid response, the state is set to success, and the did field is populated. If an invalid response is received, the state is set to error. This can be used by wallets to signal rejection by sending null, for example.

To respond to a DID request, the recipient should submit a valid DID in a DidSubmission message to the onboardEndpoint provided in the received request.

Authorizations:
ApiKey
Request Body schema: application/json
from
string <= 1000 characters

Responses

Request samples

Content type
application/json
{
  • "from": "Government Issuer"
}

Response samples

Content type
application/json
{}

Return a list of all DID requests created up to the current moment.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{}

Return an existing DID request state record by ID

This API endpoint provides information to an application about a specific DID request. When a DID is received, the state of the request is updated to success, and the did field is populated. The application can use this information to link the received DID with its system context.

Authorizations:
ApiKey
path Parameters
didRequestId
required
string <= 100 characters

id field from DID request state record

Responses

Response samples

Content type
application/json
{}

Delete existing did request state record

This API endpoint provides a way for applications to delete DID requests that are no longer needed. Deleting a request removes it from the system and frees up any resources associated with it. This operation can be useful for managing and cleaning up old or redundant requests.

Authorizations:
ApiKey
path Parameters
didRequestId
required
string <= 100 characters

id field from DID request state record

Responses

Response samples

Content type
application/json
{
  • "title": "Operation succeeded",
  • "detail": "Successfully deleted record 80194574-c2b8-4470-9618-36f7b7953574",
  • "status": 200
}

Public endpoint for holders to submit DIDs against a DID request

This API endpoint allows for submission of any valid DID, and it is up to the wallet application to implement logic for creating and/or selecting existing DIDs.

The size of the DID is limited to a maximum of 4000 characters.

NOTE: This endpoint is public and does not require authentication. Only valid links shared in DID requests should be used to submit DIDs, other request will be rejected.

Authorizations:
ApiKey
path Parameters
didRequestSubmissionId
required
string <= 100 characters

unique identifier of did request session

Request Body schema: application/json
did
required
string <= 4000 characters

Responses

Request samples

Content type
application/json
{
  • "did": "did:prism:123456"
}

Response samples

Content type
application/json
{
  • "title": "Operation succeeded",
  • "detail": "DID successfully submitted",
  • "status": 200
}

Authenticate

Create authentication challenges and track their state to act upon received responses

Create new challenge to send for authentication to another party

Creates a new challenge and the corresponding state to track the challenge by ID. The request may include an optional from parameter that enables wallets to indicate the sender of the challenge.

The created challenge state record contains a challenge field, which should be encoded and delivered to the holder, typically in the form of a QR code.

A challenge created contains a random string (nonce) that the holder must sign and submit back to the submissionEndpoint in the ChallengeSubmission format. The initial state of the record is set to pending, and if a valid response is received, the state is changed to success and the did field is populated. If an invalid response is received from the holder, either in an invalid response format or invalid signature, the state is set to error.

The id field can be used to query the challenge state over time and detect the terminal state, either success or error. Once success is detected, the application can check if the submitted DID is known in its system and take appropriate follow-up actions.

Authorizations:
ApiKey
Request Body schema: application/json
from
string <= 1000 characters

Responses

Request samples

Content type
application/json
{
  • "from": "The App"
}

Response samples

Content type
application/json
{}

Get all authentication challenges created up to date

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{}

Get the state of single authentication challenge

This endpoint provides the application with information about the status of a challenge. If the challenge has been submitted and is valid, the application can use this information to determine when to establish a new authenticated session and allow the user in, for example by creating a JWT or another authentication mechanism.

When the user submits a valid challenge response, the corresponding challenge state is updated to indicate success and the DID used to sign the challenge is saved. This allows the application to check if the DID is known in its system.

Authorizations:
ApiKey
path Parameters
challengeId
required
string <= 100 characters

id field from challenge state record

Responses

Response samples

Content type
application/json
{}

Delete an authentication challenge

This API endpoint provides a way for applications to delete challenges that are no longer needed.

Authorizations:
ApiKey
path Parameters
challengeId
required
string <= 100 characters

id field from challenge state record

Responses

Response samples

Content type
application/json
{
  • "title": "Operation succeeded",
  • "detail": "Successfully deleted challenge 645e4e90-b8f1-4072-a77b-b7e4643e43f3",
  • "status": 200
}

Public endpoint to which holders submit challenge responses

When a signed challenge is submitted to this endpoint, it is verified against the authentication key in the DID document of the DID used to sign the challenge. Each request to this endpoint invalidates the current authentication session. If an invalid request is submitted, the challenge state transitions to an error state.

The size of the did and signature fields is limited, with the DID field limited to a maximum of 4000 characters and the signature field limited to a maximum of 1000 characters. The signature field should be base64Url encoded, and the only supported DID format up to date is did:peer. did:prism support is in the works.

NOTE: This endpoint is public and does not require authentication. Only valid links shared in challenges should be used to submit challenge responses, other request will be rejected.

Authorizations:
ApiKey
path Parameters
challengeSubmissionId
required
string <= 100 characters

unique identifier of authentication challenge session

Request Body schema: application/json
did
required
string <= 4000 characters
signature
required
string <= 1000 characters

Responses

Request samples

Content type
application/json
{
  • "did": "did:peer:12345",
  • "signature": "tY63mfjyHZHN0723PgCKYZYsVHh1H6xVsh5UG9mu2qBpcV8ZWbPtfQWNUbWAv76h5UQCMBWlJRiF41r6fFJCCQ"
}

Response samples

Content type
application/json
{
  • "type": "/errors/authenticate/challenge-expired",
  • "title": "Session expired",
  • "detail": "Expired authentication challenge session.",
  • "status": 410,
  • "instance": "89c7f38c-d5e9-4b41-9903-137e63ebb397"
}