APIs

All the functionalities of the Demo Issuer are available through APIs!

We can now start working with the Demo Issuer APIs. It provides endpoints to:

• Get the Identity of the Issuer

• Issue a Claim to a specific Identity

• Fetch core information about a Claim

• Get the Revocation Status of a Claim

• Publish the state of the issuer on chain.

All the API endpoints described here can be used in Postman by importing this Collection

Get the Identity of the Issuer

• This endpoint helps get the Identity of the issuer.

• URL: http://localhost:8001/api/v1/identity

• Method: GET

Request ->

curl --location --request GET 'http://localhost:8001/api/v1/identity'

Response ->

{
    "Identifier": "113g1f1VfBXEPP7FNwgh2GGSq4KrnyqNpTH1qNnsXs",
    "State": {
        "StateID": 0,
        "Identifier": "113g1f1VfBXEPP7FNwgh2GGSq4KrnyqNpTH1qNnsXs",
        "State": "4a497ff89c3adf3518a23fdd1b95a8af3e83bea376249f41c27b40ee91f87a29",
        "RootOfRoots": "0000000000000000000000000000000000000000000000000000000000000000",
        "ClaimsTreeRoot": "facd0288b6dbc56fb13a066aa89d30dfb5065d716ea6faed5ff5fb27b8623116",
        "RevocationTreeRoot": "0000000000000000000000000000000000000000000000000000000000000000"
    }
}

Issue Claim

This endpoint helps to issue a new Claim for a specific identity.

• URL: http://localhost:8001/api/v1/claims

• Method: POST

Request ->

curl --location --request POST 'http://localhost:8001/api/v1/claims' \
--header 'Content-Type: application/json' \
--data-raw '{
    "identifier": "113g1f1VfBXEPP7FNwgh2GGSq4KrnyqNpTH1qNnsXs",
    "schema": {
        "url": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v2.json-ld",
        "type": "KYCAgeCredential"
    },
    "data": {
        "birthday": 19960424,
        "documentType": 1
    },
    "expiration": 20230101
}'

In the above example I'm issuing a claim with the following characteristics:

• issued to Identifier 113g1f1VfBXEPP7FNwgh2GGSq4KrnyqNpTH1qNnsXs

• with Schema URL https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v2.json-ld and schema type KYCAgeCredential

• containing some information about the birthday and documentType of the claim receiver

• with a specific expiration date

These data can be freely modified by the implementor according to their needs. For example, to issue a claim for a different user, you need to modify the identifierfield inside the post request.

The schema field contains information around the schema of the claim you want to issue, in the above case we are issuing a KYCAgeCredential, whose schema can be found in json-ld document as described in the url field of the schema field.

The data field provides the information contained in that specific claim to be issued. In our case it is the birthday that we need to provide. This can vary depending on the schema of your claim.

The data fields to be added to the claim are determined by the Claim Schema. To create new Claim Schemas visit Polygon ID Platform

Response ->

{"id":"7556ef4e-aaa5-41cc-b292-763b71bf4fe3"}

The response contains a single field id, namely a UUID that uniquely identifies this claim. This UUID will be later used to fetch information about this claim and check its revocation status.

Get Claim from ID

This endpoint returns information about a Claim, fetched starting from its id

• URL: http://locahost:8001/api/v1/claims/{claim_id}

• Method: GET

In the issuance process, the Issuer url is included in the claim. Every time a new issuer is launched, it will be associated with a new public url (via ngrok). With this endpoint, you can only access claims, by their id, that have been issued using the public url of the issuer you are running.

Request ->

curl --location --request GET 'http://localhost:8001/api/v1/claims/7556ef4e-aaa5-41cc-b292-763b71bf4fe3'

Response ->

{
    "id": "7556ef4e-aaa5-41cc-b292-763b71bf4fe3",
    "@context": [
        "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/iden3credential.json-ld",
        "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v2.json-ld"
    ],
    "@type": [
        "Iden3Credential"
    ],
    "expiration": "1970-08-23T05:28:21+02:00",
    "updatable": false,
    "version": 0,
    "rev_nonce": 1332052513,
    "credentialSubject": {
        "id": "113g1f1VfBXEPP7FNwgh2GGSq4KrnyqNpTH1qNnsXs",
        "birthday": 19960424.0,
        "documentType": 1.0,
        "type": "KYCAgeCredential"
    },
    "credentialStatus": {
        "id": "https://a0cb-88-147-75-172.eu.ngrok.io/api/v1/claims/revocations/1332052513",
        "type": "SparseMerkleTreeProof"
    },
    "subject_position": "index",
    "credentialSchema": {
        "@id": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v2.json-ld",
        "type": "KYCAgeCredential"
    },
    "proof": [
        {
            "@type": "BJJSignature2021",
            "issuer_data": {
                "id": "113g1f1VfBXEPP7FNwgh2GGSq4KrnyqNpTH1qNnsXs",
                "state": {
                    "claims_tree_root": "facd0288b6dbc56fb13a066aa89d30dfb5065d716ea6faed5ff5fb27b8623116",
                    "value": "4a497ff89c3adf3518a23fdd1b95a8af3e83bea376249f41c27b40ee91f87a29"
                },
                "auth_claim": [
                    "304427537360709784173770334266246861770",
                    "0",
                    "13165570127469209575864033293128926289053513756860955382551669012902460284580",
                    "12837453187469964380038269076828951349964066920458335781398485123938884929131",
                    "134020434",
                    "0",
                    "0",
                    "0"
                ],
                "mtp": {
                    "existence": true,
                    "siblings": []
                },
                "revocation_status": "https://a0cb-88-147-75-172.eu.ngrok.io/api/v1/claims/revocations/134020434"
            },
            "signature": "f683cca92a4273450f3d279f3318aa6476bbda7bcc8110c5ec8b04af49ce60ae25b39c760a2060b3c74f7c8e1a948c53c641a7e4cfcb64498b3dbe4c2e201805"
        }
    ]
}

The response contains the details of the issued claim. Without going too much into the details, the prooffield is worth being analyzed. The issuer_data field contains a snapshot of the information about the Issuer of the claim at the time of issuance. Starting from the Identity State is possible for external parties to verify that the auth_claim was part of the issuer Claims Tree and that it wasn't revoked.

Furthermore, it contains information about a signature , that is, the signature of the Claim executed by the Issuer with her Private Key at the time of the issuance.

Get Revocation Status

This endpoint returns information about the revocation status of a Claim, namely whether a claim has been revoked or not by its issuer.

• URL -> http://locahost:8001/api/v1/claims/revocations/{revocation_nonce}

• Method Type -> GET

Each claim has a unique revocation_nonce associated with it. This can be retrieved using the Get Claim from ID endpoint.

Request ->

curl --location --request GET 'http://localhost:8001/api/v1/claims/revocations/1332052513'

Response ->

{
    "issuer": {
        "state": "4a497ff89c3adf3518a23fdd1b95a8af3e83bea376249f41c27b40ee91f87a29",
        "root_of_roots": "0000000000000000000000000000000000000000000000000000000000000000",
        "claims_tree_root": "facd0288b6dbc56fb13a066aa89d30dfb5065d716ea6faed5ff5fb27b8623116",
        "revocation_tree_root": "0000000000000000000000000000000000000000000000000000000000000000"
    },
    "mtp": {
        "existence": false,
        "siblings": []
    }
}

The response contains the latest information about the state of the issuer and the Merkle tree proof (mtp) that the claim hasn't been revoked. To prove that a claim hasn't been revoked it is necessary to demonstrate that the revocation nonce does not exist existence inside the revocation tree.

Publish Identity State

• URL -> http://localhost:8001/api/v1/identity/publish

• Method Type -> POST

Until this point, the state of the issuer was never published on-chain. By calling this endpoint, the issuer's State is updated inside the State Contract (deployed on Mumbai) via a State transition function.

After the Issuer's state is published (and 3 blocks of confirmation time have passed), each Claim will also contain a second type of proof, namely a Merkle Tree proof, named as Iden3SparseMerkleProof. You can read it by calling the Get Claim from Id Endpoint

Learn more about the differences between Claims issued via Signature and by adding it to the Merkle Tree State

Request ->

curl --location --request POST 'http://localhost:8001/api/v1/identity/publish'

Response ->

{"hex":"0x5a6c7a81b2dcea26b129daca584f8775705d20d514b33c795286754a30fd0cca"}

The response contains the tx hash of the transaction submitted on-chain. You can see the details of the transaction via Polygon Mumbai Scan.

Agent Endpoint

The Demo Issuer is software that executes a set of actions (see APIs) on behalf of an identity. We can define it as an agent for the underlying identity.

This endpoint is called by external agents, such as the user Wallet, to communicate with the Demo Issuer.

• URL -> http://localhost:8001/api/v1/agent

• Method Type -> POST

This is the only endpoint that has to be exposed to the public. All the above-discussed endpoints are only called internally, as the effect of the communications handled using this endpoint.

The agent endpoint accepts a JWZ Token as its body that contains communications from an external agent, such as requests for credential issuance

In our KYC-Age Demo Application, Polygon ID wallet will use this endpoint to fetch a claim issued for the Identifier associated with that Wallet.