Skip to main content

Type of Authorization Requests

The proof generation by the wallet SDK is based on two types of authorization requests sent by the Verifier (or also by the Issuer in the case of Basic Auth):

Basic Auth Request​

The Issuer/Verifier sends the Basic Auth request to the wallet when the user needs to prove its identity (based on the Identifier generated earlier) to the Issuer/Verifier. This request is sent when an Identity needs to prove that it is, indeed, what it asserts to be.

Structure of Basic Auth Request​

The structure of a Basic Auth request can be seen below:

{
 "id": "6c004daa-b664-4c1a-8393-66ef6755a07b",
 "thid": "6c004daa-b664-4c1a-8393-66ef6755a07b",
 "from": "1125GJqgw6YEsKFwj63GY87MMxPL9kwDKxPUiwMLNZ",
 "typ": "application/iden3comm-plain-json",
 "type": "https://iden3-communication.io/authorization/1.0/request",
 "body": {
   "reason": "test flow",
   "message": "",
   "callbackUrl": "https://verifier-demo.polygonid.me/api/callback?sessionId=95209",
   "scope":
 }
}

where:

  • id: Identifier stored on the wallet SDK
  • thid: ID of the message thread
  • from: from where the authentication request comes, i.e. the identifier of the identity from which a Verifier requests proof
  • typ: iden3comm Media Type, i.e. file format for the type field. (For example, JSON)
  • type: type of iden3comm Protocol Message; type of request; it could be an auth request, proof request, or a credential offer
  • reason: reason of authentication (it could be age verification or simply a test flow)
  • message: message to be signed; can be left blank
  • callbackUrl: URL to which requested information is sent and response is received
  • scope: information related to the proof request and the requirements to be fulfilled by the proof generated and shared from mobile. It is in the form of an array of proofs that the SDK generates.

Query-based Request​

A Query-Based Request is used for generating two types of proofs: Signature-based Proof and Merkle Tree Proof (MTP). For such proofs, we have a credential that satisfies pre-determined criteria (as can be seen from the structure of the Query-based Request below) and these credentials are used for generating the proofs and shared with the Verifier using callbackUrl.

Structure of Query-based Request​

{
 "id": "b5d9edf2-adcf-4600-b273-1f6f32da87ee",
 "thid": "b5d9edf2-adcf-4600-b273-1f6f32da87ee",
 "from": "1125GJqgw6YEsKFwj63GY87MMxPL9kwDKxPUiwMLNZ",
 "typ": "application/iden3comm-plain-json",
 "type": "https://iden3-communication.io/authorization/1.0/request",
 "body": {
   "reason": "test flow",
   "message": "",
   "callbackUrl": "https://verifier-demo.polygonid.me/api/callback?sessionId=932469",
   "scope": {
     "0": {
       "id": "1",
       "circuit_id": "credentialAtomicQuerySig",
       "rules": {
         "query": {
           "allowedIssuers":
               "0": "*",
           "schema": {
               "type": "KYCAgeCredential",
               "url": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v2.json-ld"
           },
           "req": {
               "birthday": {
                   "$lt": "20000101"
             }
           }
         }
       }
     }
   }
 }
}

where:

  • id: Identifier stored on the wallet SDK
  • thid: ID of the message thread
  • from: from where the authentication request comes, i.e. the identifier of the identity from which a Verifier requests proof
  • typ: iden3comm Media Type, i.e. file format for the type field. (For example, JSON)
  • type: type of iden3comm Protocol Message; type of request; it could be an auth request, proof request, or a credential offer
  • reason: reason of authentication (it could be age verification or simply a test flow)
  • message: message to be signed; can be left blank
  • callbackUrl: URL to which requested information is sent and response is received
  • scope: information related to the proof request and the requirements to be fulfilled by the proof generated and shared from mobile. It is in the form of an array of proofs that the SDK generates.
  • 0:
  • id: Scope id
  • circuit_id: type of proof; in the above example, it is credentialAtomicQuerySig.
  • rules:
  • query:
  • allowedissuers: types of Issuers allowed
  • 0: "*" : all types of Issuers are allowed
  • schema: a structure that is used for proof generation for a credential
  • type: type of credentials allowed
  • url: URL for getting the vocabulary for the credential
  • req: a query request to a query circuit; for example, the user's birthday should fall before January 1, 2000

Difference Between Basic Auth and Query-based Requests​

The difference between the proofs based on Basic Auth and Query-based requests is that the Basic Auth is used by an identity for authenticating itself (as was mentioned above) and the Query-based is used for authenticating the credentials that the Identity receives from an Issuer.

The fundamental structure of the request types is the same except that the Query-based request carries more parameters: in the form of more information linked to the proof generated by the wallet SDK; it includes information such as type of credentials allowed, URL for getting vocabulary for those credentials and requirements that a credential must satisfy (ex, the birthdate should be more than 18).

Auth Circuit and AtomicQuerySig Circuit​

A circuit is a zero-knowledge based program that generates a ZK proof based on a set of inputs provided. An Auth Circuit creates a proof for the Basic Auth requests and AtomicQuerySig Circuit generates proof for signature-based requests AtomicQueryMTP is used for the MTP-based requests.

For more information on circuits, go through the following links:

auth circom

credentialAtomicQuerySigV2

credentialAtomicQueryMTPV2

How is Proof sent to the Verifier?​

The wallet sends the proof generated to a Verifier using a callbackUrl; this URL is included in the auth request and includes the information that the Verifier requests from the Wallet. So, the Wallet sends the proof request along with the credential via this callbackUrl and receives the proof response from the Verifier on the same URL.