ProofSpace provides the following integration points:
Called by ProofSpace:
Action Interaction Webhook
Credential Check Webhook
Called by third-party:
Credential Issuing Webhook
Webhook calls are performed as HTTPS Post requests, where input and output are json encoded values.
Authentication Schemas
We support two authentication schema:
Request Signature
Each call should have an additional X-Body-Signature header with the value of the third-party’s sha3-256 signature in base64 encoding. ProofSpace and third-parties should exchange public keys before integration.Bearer Token
Each call should have an Authorization header with the valueBearer {token}
, where the token is a base64 representation of the JsonWebToken as defined in RFC 7519.
In the request from ProofSpace, 'iss' field is a public DID of the service[^1].
In request to ProofSpace, 'aud' field should be a public DID of the service.
ProofSpace and third-parties should exchange public keys of sha secrets before integration.
Repository https://github.com/zakaio/docs-and-examples contains examples.
Description of calls
Interaction Webhook
An interaction webhook can be called while the user performs an interaction.
It receives information about current activity and received credentials (details below) and may return information about issued credentials.
The input contains the following fields:
publicServiceDid: string; -- public DID of service which owns the action.
subscriberConnectDid: string; -- connect DID of the subscriber to this service.
actionId: string; // action template
actionInstanceId: string; // action instance.
actionEventId: string; // id of the event (unique for service)
actionParams: {name: string, value: string}[]; // array of parameters, configured in action
receivedCredentials: WebhookCredentialValuesDTO[ ] ; //array of required credentials.
Where WebhookCredentialValuesDTO consists of:
credentialId: string; // credentialId
schemaId: string; // schemaId
fields: { name: string, value: string }[]; // credentials from phone
utcIssuedAt: number; // utc time in milliseconds
revoked: boolean; // is this credential revoked. (optional)
utcRevokedAt?: number; // time when credential was revoked (optional).
Webhook in case of success invocation should return json with the following fields:
serviceDid: string; // public service DID, should be the same as in request
subscriberConnectDid: string; // connect DID, should be the same as in request
actionEventId: string; // event
issuedCredentials: WebhookCredentialValuesDTO[ ]; // array of issued credentials.
revokedCredentials: [] // can be kept as an empty array
Note: if third-party systems want to deny or postpone the issuing of a credential back to a user, then it should return credentials with empty fields and the revoked flag set to true.
Credential Check Webhook
Can be configured to perform validation of credentials behind ProofSpace (such as checking that the hash is present in the blockchain or checking the root authority of the certificate).
It should accept json with the following fields:
serviceDid: string; // public DID of service, which call action
subscriberDid: string; // connect DID of subscriber
credentialId: string; // credentialId, registered in blockchain
schemaId: string; // schema id
fields: { name: string, value: string } []; // array of fields.
and return the structure with the following fields:
ok: boolean; // true if check was successful, false otherwise.
errorMessage?: string // optional error message if check was unsuccessful
extra: // optional extra information which contains
schemaId?: string; // optional schemaId of returned fields. If present - info should contain fields from this schema, otherwise info contains fields in any form.
info: { name: string, value: string }[]; //values
format: string; // optional format description for values, encoded in info. should be ‘plain’ or ‘json’.
Credential Issue Webhook
Credential issued webhook is called by the third-party to ProofSpace server via URL:
<container-root>/service/:serviceDid/webhook-accept/credendials-issued
i.e. for the SaaS installation, this should be:
https://platform.proofspace.id/service/:serviceDid/webhook-accept/credentials-issued/.
where: serviceDid is a public DID of the credential owner.
ProofSpace accepts the structure with the following fields:
serviceDid: string; // public DID of service which issues credential, the same as in the query path.
subscriberConnectDid: string; // connect DID of subscriber for this service
credentials: WebhookCredentialValuesDTO[]; // array of credentials issued. (the same as in ‘action’ webhook).
issuedAt: UTC timestamp of issued date in milliseconds.
And the returned structure is:
ok: boolean // if credential setting was successful
error?: // optional block which contains message
message: string;
Retrieving Service Public Key webhook
This functionality by the third-party to ProofSpace server via URL:
<container-root>/service/:serviceDid/public-info/public-key/name
<!-- Footnotes themselves at the bottom. -->
Notes
[^1]:
A “service” is an instance of the ProofSpace Dashboard. ProofSpace charges a subscription fee per service and all interactions for a service will be created and monitored in the Dashboard for that service.