Core Credential API

[ChakshuGautam]

Example Use Cases

1. APIs to issue, verify an present a credential with each of the process being decoupled - verify could be an offline verification as well. Issue can be on a different system. Present could be done on an offline application or over network.
2. APIs to be broken down in a way that allows different workflows to be done based on 1.

Specific Priority Use Cases

1. Programmatic issuance (at scale): The state education department has digitally verified data of students enrolled in government schools across the state. The state wants to programmatically issue enrolment credentials to all the digitally verified students so that the students can view these credentials and be able to share them through the digital wallet provided by the state education department

2. Issuance (at scale): Sharmila, principal of a private school wants to issue an enrolment credential to Meghna using the enrolment credential template provided by the state education department. After generating the enrolment credential Meghna can view the enrolment credential in the wallet provided by the state education department

3. Verifiable presentation (for pilot): Mohan, a grade 12 student wants to apply online to a private coaching centre and when he starts his application he gets an option to 'Apply via Wallet'. Mohan chooses this option and then provides consent to the coaching centre to view the necessary details from his set of credentials stored in his digital wallet provided by the state education department.

Suggested Solution

Example W3C VC APIs VC-API

[dileepbapat]

I see 2 problems

• VC-API mentioned, GET /credentials is wide and may not be required since it allows enumeration of creds
• /credentials/issue will need identity to update certificate.

[pramodkvarma]

Can one of you paste the W3C APIs link here?

Agree @dileepbapat that credential enumeration may not be appropriate. Also, issuance and update of credentials are needed. Maybe same API or separate APIs.

[tejash-jl]

Can one of you paste the W3C APIs link here?

Agree @dileepbapat that credential enumeration may not be appropriate. Also, issuance and update of credentials are needed. Maybe same API or separate APIs.

https://w3c-ccg.github.io/vc-api/

[suresh12]

Following are the recommendations to have cleaner APIs for Credentials.

Separation of Schema/Template from Credentials
Separation of Credential Schema from Credentials makes it easier to manage schema and rendering templates for the schema. The Schemas have tags as additional metadata that allows for finding similar schemas. The Schemas are also publicly resolvable by just typing the name of the schema after the base URL.

Schema APIs
Filter by Tags
GET - /credential-schema/?q=[tags]
Output:
{
https://w3c-ccg.github.io/vc-json-schemas/#vc_example
}

GET - /credential-schema/:id
Output:
{
schema: https://w3c-ccg.github.io/vc-json-schemas/#vc_example
tags: [""],
templates: [{Rendering Templates}]
}

POST - /credential-schema
Input:
{
schema: https://w3c-ccg.github.io/vc-json-schemas/#vc_example,
tags: [“”]
}

PUT - /credential-schema/:id
Input:
{
https://w3c-ccg.github.io/vc-json-schemas/#vc_example,
tags: [“”]
}

Rendering Template APIs
GET /rendering-template/:schemaId
Output:
{
template: “<string | buffer>”,
type: “<Handlebar | …>”,
schema: schemaId
}

GET /rendering-template/:id
Output:
{
template: “<string | buffer>”,
type: “<Handlebar | …>”,
schema: schemaId
}

POST /rendering-template
Input:
{
template: “<string | buffer>”,
type: “<Handlebar | …>”,
schema: schemaId
}

PUT /rendering-template
Input:
{
template: “<string | buffer>”,
type: “<Handlebar | …>”
schema: schemaId
}

W3C based Credential APIs

POST - /credentials/issue
Input:
{
credential: https://w3c-ccg.github.io/vc-api/issuer.html#tag/Credentials/operation/issueCredential,
credentialSchema: https://w3c-ccg.github.io/vc-json-schemas/v1/index.html#credential_schema_definition
}

The credentialSchema is verified before creating a credential. This is done to allow a certain type of credentials to be issued through a service. If the field is null, a credential issuance request should be rejected. (This can be config based at a tenant)
This is a deviation from the W3C but in some use cases, it is essential only a certain type of credentials be generated through this and the schema is globally debated before being inserted to the schema repository. Similar to the practice here.

POST - /credentials/verify
Input:
{
https://w3c-ccg.github.io/vc-api/verifier.html#tag/Credentials/operation/verifyCredential
}

GET - /credentials/getById
Input: {
https://w3c-ccg.github.io/vc-api/holder.html#tag/Credentials/operation/getCredential
}

POST - /credentials
Input: {
https://w3c-ccg.github.io/vc-api/holder.html#tag/Credentials/operation/getCredentials
Subject: {identity-ref},
Issuer: {identity-ref}
}

Finding credentials by issuer and by subject should be supported by RC, even though it is not available in W3C. For that purpose API is changed to POST API.

POST /credentials/render
Input: {
credentials: {VC JSON},
schema: {Schema JSON},
template: {template string/buffer},
output: {QR | QR link | html | string | json | shortened URL}
}

[tejash-jl]

We had an internal call to discuss the above recommendations and below are the action items for the same:
Participants: (Tejash, Dileep, Chakshu, Suresh, Parth, Ashwin, Snehal)

• We have decided to create a wrapper service to support the above W3C based VC API
• Need to prioritize the implementation as its a blocker for ULP usecase
• Have a call with Sasi to discuss on the key management service (https://github.com/orgs/Sunbird-RC/discussions/317 )
• @ChakshuGautam to share/create a PR of his current work on the VC apis
• Presentation API can be low prioritised,
• Create a revocation list API as per https://w3c-ccg.github.io/vc-status-rl-2020/

[pramodkvarma]

Super! 👍

[tejash-jl]

@ChakshuGautam
Below are the links for credential schema and issuance APIs that we have finalised,
https://sunbirdrc-sandbox.xiv.in/issue-api.html
https://sunbirdrc-sandbox.xiv.in/schema-api.html
Let us know if any changes are required, we will start working on creating the APIs from next week

[ChakshuGautam]

Hey, @tejash-jl we have built some core credentialing APIs and would like to contribute. Can we sync up tomorrow once and you can help me raise a PR for this?

[ChakshuGautam]

A couple of credential rendering APIs are missing from this as well. Can we discuss those as well? Thanks.

[tejash-jl]

Sure @ChakshuGautam,
pinged you on discord

[pramodkvarma]

How does search work especially how does the consent of the credential holder is handled?

Second question, how does different type of credentials work with these same APIs? I am a bit confused. Maybe @tejash-jl can walk me through this sometime next week? @surendrasinghs please help coordinate. Thanks.

[ChakshuGautam]

Hey, @tejash-jl can you please include me in this call as well? Started a discussion on Consent here to get more clarity on the topic.

[surendrasinghs]

We had a quick discussion and review of this today with a few community members. Requesting your review comments @amarts @girirajdaga @sankarshanmukhopadhyay @dileepbapat @vrayulu @coolbung @smohan-dw @rahul101001000

Here's the recording. Use passcode: *iR3zyH&

Below are the links for credential schema and issuance APIs that were reviewed today
https://sunbirdrc-sandbox.xiv.in/issue-api.html
https://sunbirdrc-sandbox.xiv.in/schema-api.html

[sankarshanmukhopadhyay]

I don't have specific comments about the API (I'll defer to Amar on that). However, I would like for us as a group to explore how a "genesis" (or starting) repository of schemas can be available as a public resource and other entities (organizations, individuals etc.) can contribute to it after suitable validation and linting have been completed. New schemas, including derived schemas (proof of A also repurposed to be the basis of proof of B type), will be common. Good versioning would be needed so that the downstream consumption of the schemas is intact because of incompatible changes introduced upstream.

The schema will become an integral component of the trust ecosystem of credentials and thus should allow good audit practices and control.

[rahul101001000]

Thanks @surendrasinghs!

Few suggestions @tejash-jl @ChakshuGautam on sunbirdrc-sandbox.xiv.in/schema-api.html

1. Let's have a more detailed example that is more real. Right now description just says Email, doesn't seem like a real credential. See this for a good example
2. If I wanted to verify that the author indeed uploaded this, can I? Right now proof only seems to have the hash of the content, it is not signed by the author. Is that right?
3. Assuming author field will be a did and not just text.
4. Minor typos/errors exist in the schema e.g. POST doesn't have author while response has it. Spelling error in Create redenring templates

Thanks!

Regards
Rahul

[surendrasinghs]

Thanks, Rahul. +1 to having good examples - adding to your suggestions...

Chakshu, Tejash, I am jotting down my thoughts on these APIs here... Please let me know if there is any another way I should route my feedback

1. Please use singular "credential" instead of "credentials" (unless we really mean plural).
2. Please provide description against each of the API request parameters. It would help understand what will go where and visualize use-cases.
3. If possible, please create a few examples.

I would be happy to add description to APIs or write use-cases for examples. How/Where can I contribute/collaborate?