Share on facebook
Share on twitter
Share on linkedin

API Update: Verification Policies

Verifications are a core part of SSI. The unique value proposition of SSI is that information can be verified instantly and cryptographically, without managing multiple integrations. Recently we published an update to our platform with a new approach to verifications. Above all, this update will make verifiable credentials more intuitive and easier to use. It will also increase code maintainability, provide a more future-proof abstraction, and keep our API in line with the most recent changes to the open source codebases.

 

For these reasons, we updated the data model associated with verifications in our platform. On the API and Developer Portal, we’ve discontinued Verification Definitions — all API endpoints under /definitions/verifications/ are now marked as obsolete. We’ve named the new approach Verification Policies. Although we’ll continue to support Verification Definitions for at least 90 days from now, we encourage all our existing users to switch to the new data model as soon as possible to reduce the likelihood of issues.

 

 

Problems with Verification Definitions

 

Knowledge Gap

Verification Definitions’ data model mapped directly to Indy SDK data structures. This means that one must learn the internals of how Indy works (which is counterintuitive, to put it nicely) in order to construct a valid proof request. This unfortunately resulted in confusion from the standpoint of our users despite robust documentation.

 

 

Future-proof Abstraction

The Verification Definition approach was so tightly coupled to Indy that adding support for other DID methods or verifiable credential models would be tricky. Our intention is to be ‘ledger agnostic’ by supporting evolving protocols, new signature schemes, and more. Seeing these advancements on the horizon, we realized we needed a more future-proof abstraction that is both flexible and scalable.

 

 

Validation

Because the Verification Definition data model was used to directly invoke Indy SDK functions, validation of inputs was a challenge. There was little room to do validation of the requests, or the validation had to be done using anti-patterns. Verification Policies (among other things) makes it easier to ensure the attribute you’re requesting is present in the schema for the credential you’re interested in.

 

 

Crowded Endpoints

Lots of functionality was baked into a small number of Verification Definition API endpoints. That means that different functions were called depending on the data in the request. We’ve learned from feedback from our users that this was not very intuitive. Endpoints should have a single purpose without side effects.

 

 

No Grouping

Verification Definitions constructed proof requests that were attribute-based. They allowed for per-attribute validation but didn’t support grouped attributes. That created a loophole where, as long as a user had more than one credential from the same schema, the verifier had no way to know whether the user’s proof presentation was from the same credential.1

 

 

Verification Policies

The architecture and design of Verification Policies solve all five problems with Verification Definitions. Specifically, Verification Policies:

 

  1. Are much more intuitive than Verification Definitions because the data model maps more closely to the practical reality of the verifier’s requirements and adheres less to a low-level technical model
  2. Provide an abstraction beyond Indy which will enable support for other protocols as they mature
  3. Enable better validation of inputs
  4. Gave us an opportunity to break out each separate functionality into its own endpoint
  5. Utilized a recent update to Indy SDK which enabled grouping of attributes from a credential

Verification Policies will be very familiar to anyone who has previously used Verification Definitions. But now, a single verification request can contain as many policies as the use case requires. There are two kinds of policies.

1. Attribute policies: These are straightforward verifications of attributes based on a credential; after specifying a credential to verify, you can select as many attributes from that credential as you like.

As a verifier, you can select the kind of credential you want to verify, as well as the attributes from that credential that you’d like to verify. In this case, the verifier is verifying name, address, and ID#.

2. Predicate policies: These are zero-knowledge proofs; you can select a single attribute from a credential to verify conditionally (for example, whether age is greater than 18).

 

As a verifier, you can also select attributes to perform conditional validation on. In this case, the verifier is requiring the weight listed on the driver’s license be above 120.

 

 

API Updates & New Endpoints

At Streetcred our aim is to be the best way for developers to implement SSI. We strive to build our APIs with intuitive data structures that abstract the low-level technical contracts away, exposing a higher-level representation of user flows. These updates mandated the creation of new endpoints and the deprecation of old ones. New endpoints can be found under /verificationPolicies/*. With the API, you can:

  • Set up and save attribute policies
  • Set up and save predicate policies
  • Construct verifications based on one or more policies
  • Construct verifications without policies (by creating a one-time use policy on the fly)
  • Send verifications to an existing connection
  • Generate a resolvable URL that you can send connectionless

Guides, including the specific endpoints and directions on how to use them, can be found in our documentation.

 

Developer Portal UI Update

The Streetcred Developer Portal is a user interface built on top of the API. When developing the interface, we’ve been careful to balance usability with flexibility. For simplicity’s sake, the Developer Portal allows you to:

  • Construct verifications based on policies
  • Send verifications to an existing connection
  • Generate a resolvable URL that you can send connectionless

Screenshots of the updated UI are included above.

 

Streetcred Wallet UI Update

The Streetcred Wallet is a user-friendly, general-purpose mobile application that stores credentials and other SSI-related information on the user’s device. It was a design challenge to support both Verification Definitions & Policies in the user interface. We believe the current approach balances usability, simplicity, and function.

Old UI: This is how the app looked using Verification Definitions.

Updated UI: When a proof request is sent using a Verification Definition, each one is seen separately in the UI.

Updated UI: When a proof request is sent using Verification Policies, attributes can be grouped according to the credential they come from.

 

Try It Out

We believe Verification Policies will make it easier for developers, enterprises, and everybody in between to interact with verifiable credentials. If you haven’t already, sign up at studio.trinsic.id and verify some credentials today! If you have questions, you can refer to the documentation or reach out to support@trinsic.id.

Notes

1. Example of how the no grouping works:

Imagine Charlie loves going to concerts. He buys tickets for two different concerts in a single weekend. TicketKingdom issues him two verifiable credentials representing concert tickets.

  • Ticket A: Concert name: Taylor Swift, Seat location: nosebleed
  • Ticket B: Concert name: Random no-name band, Seat location: front-row

When Charlie arrives at the Taylor Swift concert, the ticket booth will send him a proof request asking for his ticket details. If the ticket booth used Verification Definitions, then Charlie can use ‘Concert name’ from Ticket A and ‘Seat location’ from Ticket B. Because the validation is done on a per-attribute basis, the proof presentation will appear valid to the ticket booth.