Claims

OpenAPI documentation for the Claims module

Claim credential

Claim specific credential. User has to pass authorization token in header and data in request body. authorization header has to contain Bearer and token returned from previous token endpoint. In request body user has to pass types array with type of credential being claimed, format string with format of the credential, and proof object with proof_type string and jwt string. proof_type is a string that represents the type of the proof, which is in our case jwt. jwt is a string that represents the JWT token which is generated by wallet and acts as a proof of posession JWT. If successful, the server returns an object with credential, format, c_nonce and c_nonce_expires_in properties. credential is a string that represents the JWT token which contains all the details about the claimed credential. format is a string that represents the format of the credential. c_nonce is a string that represents c-nonce and c_nonce_expires_in is a number that represents the expiration time of the c-nonce in seconds.

POST../public/{correlationId}/credentials

Path parameters

correlationId*string

The correlation ID defined on the server (nchain in our case).

Header parameters

Body

types*array of array

The type of the credential we choose when issuing.

format*string

The format of the credential we choose when issuing.

Example: "jwt_vc_json"

proof*CorrelationCredentialProofDto (object)

Response

Body

credential*string

JWT token which contains all the details about the claimed credential.

Example:

"eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QifQ.eyJleHAiOjE3MDg1Mjg4NjIsInZjIjp7IkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIl0sInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJDaGFyYWN0ZXJDcmVkZW50aWFsIl0sImNyZWRlbnRpYWxTdWJqZWN0Ijp7Im5hbWUiOiJZZWxsb3ciLCJiaW9ncmFwaHkiOiJZb3UmI3gyNztyZSBjaGVlcmZ1bCBhbmQgb3B0aW1pc3RpYywgYnJpbmdpbmcgam95IGFuZCBwb3NpdGl2aXR5IHdoZXJldmVyIHlvdSBnby4gWW91ciBzdW5ueSBkaXNwb3NpdGlvbiBhbmQgaW5mZWN0aW91cyBsYXVnaHRlciBicmlnaHRlbiBldmVuIHRoZSBkYXJrZXN0IG9mIGRheXMuIFdpdGggYSBoZWFydCBmdWxsIG9mIGNvbXBhc3Npb24gYW5kIGVtcGF0aHksIHlvdSYjeDI3O3JlIGFsd2F5cyByZWFkeSB0byBsZW5kIGEgaGVscGluZyBoYW5kIHRvIHRob3NlIGluIG5lZWQuIiwidHlwZSI6IkNoYXJhY3RlciBDcmVkZW50aWFsIiwiaWQiOiJkaWQ6YnN2OmVjYWE0MDI4ZWMzYzM2N2IwZTkwNzI3ZmI1ZTY3ZWQwMTczNjA0ZWE2ZmVjYzRiMmM4YzI4ZTFlNjQxMjYyMTQifX0sIkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIl0sInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJDaGFyYWN0ZXJDcmVkZW50aWFsIl0sImV4cGlyYXRpb25EYXRlIjoiMjAyNC0wMi0yMVQxNToyMTowMi44MDlaIiwiY3JlZGVudGlhbFN1YmplY3QiOnsibmFtZSI6IlllbGxvdyIsImJpb2dyYXBoeSI6IllvdSYjeDI3O3JlIGNoZWVyZnVsIGFuZCBvcHRpbWlzdGljLCBicmluZ2luZyBqb3kgYW5kIHBvc2l0aXZpdHkgd2hlcmV2ZXIgeW91IGdvLiBZb3VyIHN1bm55IGRpc3Bvc2l0aW9uIGFuZCBpbmZlY3Rpb3VzIGxhdWdodGVyIGJyaWdodGVuIGV2ZW4gdGhlIGRhcmtlc3Qgb2YgZGF5cy4gV2l0aCBhIGhlYXJ0IGZ1bGwgb2YgY29tcGFzc2lvbiBhbmQgZW1wYXRoeSwgeW91JiN4Mjc7cmUgYWx3YXlzIHJlYWR5IHRvIGxlbmQgYSBoZWxwaW5nIGhhbmQgdG8gdGhvc2UgaW4gbmVlZC4iLCJ0eXBlIjoiQ2hhcmFjdGVyIENyZWRlbnRpYWwiLCJpZCI6ImRpZDpic3Y6ZWNhYTQwMjhlYzNjMzY3YjBlOTA3MjdmYjVlNjdlZDAxNzM2MDRlYTZmZWNjNGIyYzhjMjhlMWU2NDEyNjIxNCJ9LCJpc3N1ZXIiOiJkaWQ6YnN2OmQ3ZGRjYzAwYzE0ZjliY2NlMTEzNWZjM2IzMjYxNGExYjNiNDcyMGJlNjQwNDUwNzQzYmE2Yjg1MTk4MzMyNWQiLCJpc3N1YW5jZURhdGUiOiIyMDI0LTAyLTE0VDE0OjIxOjAyLjgxMFoiLCJzdWIiOiJkaWQ6YnN2OmVjYWE0MDI4ZWMzYzM2N2IwZTkwNzI3ZmI1ZTY3ZWQwMTczNjA0ZWE2ZmVjYzRiMmM4YzI4ZTFlNjQxMjYyMTQiLCJuYmYiOjE3MDc5MjA0NjIsImlzcyI6ImRpZDpic3Y6ZDdkZGNjMDBjMTRmOWJjY2UxMTM1ZmMzYjMyNjE0YTFiM2I0NzIwYmU2NDA0NTA3NDNiYTZiODUxOTgzMzI1ZCJ9.BNtaFqWdZNCmCXodN8tZ5MHOflzxQnbnFnYAJcWruQMXF-l8V4c2nsyb-3mgdGy38SowpJgHplZri6-TkcM_mA"

format*string

The format of the credential.

Example: "jwt_vc_json"

c_nonce*string

String representing c-nonce.

Example: "bea65ef2-ebd3-4006-b095-e5fbd6d96ccd"

c_nonce_expires_in*number

Number representing the expiration time of the c-nonce in seconds.

Example: 300000

Request

const response = await fetch('../public/{correlationId}/credentials', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "types": [
        "EmailCredential"
      ],
      "format": "jwt_vc_json",
      "proof": {
        "proof_type": "jwt",
        "jwt": "eyJ0eXAiOiJvcGVuaWQ0dmNpLXByb29mK2p3dCIsImFsZyI6IkVTMjU2SyIsImtpZCI6ImRpZDpic3Y6ZWNhYTQwMjhlYzNjMzY3YjBlOTA3MjdmYjVlNjdlZDAxNzM2MDRlYTZmZWNjNGIyYzhjMjhlMWU2NDEyNjIxNCNzdWJqZWN0LWtleSJ9.eyJpYXQiOjE3MDcyOTUyOTEuMjEsImV4cCI6MTcwNzI5NTk1MS4yMSwiYXVkIjoiaHR0cHM6Ly84ZmNmLTIxMy0xNzItMjM0LTgxLm5ncm9rLWZyZWUuYXBwL25jaGFpbiIsIm5vbmNlIjoiNTc1NTUzZTgtMDQ1NS00YjAyLThmNGMtNmRmNmY2MTMxZDEzIiwiaXNzIjoibkNoYWluOnZjLXdhbGxldCIsImp0aSI6IjJkMzg4ZDE1LWFjY2QtNGI0My1hZWExLTUyOTg5YTY4YmJjOSJ9.Pd0RiOb9c1fcjFGUQCNW01QCHdc7-Dz9NAdh93yOzYQnXqjmr0joyezqCEbeNxRacSsl7GNAB8IfsDkEthPfyg"
      }
    }),
});
const data = await response.json();

Response

{
  "credential": "eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QifQ.eyJleHAiOjE3MDg1Mjg4NjIsInZjIjp7IkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIl0sInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJDaGFyYWN0ZXJDcmVkZW50aWFsIl0sImNyZWRlbnRpYWxTdWJqZWN0Ijp7Im5hbWUiOiJZZWxsb3ciLCJiaW9ncmFwaHkiOiJZb3UmI3gyNztyZSBjaGVlcmZ1bCBhbmQgb3B0aW1pc3RpYywgYnJpbmdpbmcgam95IGFuZCBwb3NpdGl2aXR5IHdoZXJldmVyIHlvdSBnby4gWW91ciBzdW5ueSBkaXNwb3NpdGlvbiBhbmQgaW5mZWN0aW91cyBsYXVnaHRlciBicmlnaHRlbiBldmVuIHRoZSBkYXJrZXN0IG9mIGRheXMuIFdpdGggYSBoZWFydCBmdWxsIG9mIGNvbXBhc3Npb24gYW5kIGVtcGF0aHksIHlvdSYjeDI3O3JlIGFsd2F5cyByZWFkeSB0byBsZW5kIGEgaGVscGluZyBoYW5kIHRvIHRob3NlIGluIG5lZWQuIiwidHlwZSI6IkNoYXJhY3RlciBDcmVkZW50aWFsIiwiaWQiOiJkaWQ6YnN2OmVjYWE0MDI4ZWMzYzM2N2IwZTkwNzI3ZmI1ZTY3ZWQwMTczNjA0ZWE2ZmVjYzRiMmM4YzI4ZTFlNjQxMjYyMTQifX0sIkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIl0sInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJDaGFyYWN0ZXJDcmVkZW50aWFsIl0sImV4cGlyYXRpb25EYXRlIjoiMjAyNC0wMi0yMVQxNToyMTowMi44MDlaIiwiY3JlZGVudGlhbFN1YmplY3QiOnsibmFtZSI6IlllbGxvdyIsImJpb2dyYXBoeSI6IllvdSYjeDI3O3JlIGNoZWVyZnVsIGFuZCBvcHRpbWlzdGljLCBicmluZ2luZyBqb3kgYW5kIHBvc2l0aXZpdHkgd2hlcmV2ZXIgeW91IGdvLiBZb3VyIHN1bm55IGRpc3Bvc2l0aW9uIGFuZCBpbmZlY3Rpb3VzIGxhdWdodGVyIGJyaWdodGVuIGV2ZW4gdGhlIGRhcmtlc3Qgb2YgZGF5cy4gV2l0aCBhIGhlYXJ0IGZ1bGwgb2YgY29tcGFzc2lvbiBhbmQgZW1wYXRoeSwgeW91JiN4Mjc7cmUgYWx3YXlzIHJlYWR5IHRvIGxlbmQgYSBoZWxwaW5nIGhhbmQgdG8gdGhvc2UgaW4gbmVlZC4iLCJ0eXBlIjoiQ2hhcmFjdGVyIENyZWRlbnRpYWwiLCJpZCI6ImRpZDpic3Y6ZWNhYTQwMjhlYzNjMzY3YjBlOTA3MjdmYjVlNjdlZDAxNzM2MDRlYTZmZWNjNGIyYzhjMjhlMWU2NDEyNjIxNCJ9LCJpc3N1ZXIiOiJkaWQ6YnN2OmQ3ZGRjYzAwYzE0ZjliY2NlMTEzNWZjM2IzMjYxNGExYjNiNDcyMGJlNjQwNDUwNzQzYmE2Yjg1MTk4MzMyNWQiLCJpc3N1YW5jZURhdGUiOiIyMDI0LTAyLTE0VDE0OjIxOjAyLjgxMFoiLCJzdWIiOiJkaWQ6YnN2OmVjYWE0MDI4ZWMzYzM2N2IwZTkwNzI3ZmI1ZTY3ZWQwMTczNjA0ZWE2ZmVjYzRiMmM4YzI4ZTFlNjQxMjYyMTQiLCJuYmYiOjE3MDc5MjA0NjIsImlzcyI6ImRpZDpic3Y6ZDdkZGNjMDBjMTRmOWJjY2UxMTM1ZmMzYjMyNjE0YTFiM2I0NzIwYmU2NDA0NTA3NDNiYTZiODUxOTgzMzI1ZCJ9.BNtaFqWdZNCmCXodN8tZ5MHOflzxQnbnFnYAJcWruQMXF-l8V4c2nsyb-3mgdGy38SowpJgHplZri6-TkcM_mA",
  "format": "jwt_vc_json",
  "c_nonce": "bea65ef2-ebd3-4006-b095-e5fbd6d96ccd",
  "c_nonce_expires_in": 300000
}

Get access token to start the credential issuance.

Before claiming the credential, the user has to get an access token. This endpoint facilitates the retrieval of an access token with the provided client_id, grant_type and pre-authorized_code. The client_id is a string that represents the client ID. The grant_type is a string that represents the grant type, which is in our case urn:ietf:params:oauth:grant-type:pre-authorized_code. The pre-authorized_code is a string that represents the pre-authorized code, which is generated by the web client when creating an offer. If successful, the server returns an object with access_token, token_type, expires_in, c_nonce, c_nonce_expires_in, authorization_pending and interval properties. access_token is a string that represents the access token. token_type is a string that represents the token type (bearer in our case). expires_in is a number that represents the expiration time of the token in seconds. c_nonce is a string that represents the c-nonce. c_nonce_expires_in is a number that represents the expiration time of the c-nonce in seconds. authorization_pending is a boolean that indicates if the authorization is pending (not used in our case). interval is a number that represents the interval in milliseconds.

POST../public/{correlationId}/token

Path parameters

correlationId*string

The correlation ID defined on the server (nchain in our case).

Body

client_id*string

The client ID.

Example: "nChain:vc-wallet"

grant_type*string

The grant type to use

Example: "urn:ietf:params:oauth:grant-type:pre-authorized_code"

pre-authorized_code*string

Pre Authorized code that references the credential to start token fetching

Example: "ab407be3-d18f-4508-837e-6286329c1da2"

Response

Body

access_token*string

String representing access token

Example:

"eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksifQ.eyJpYXQiOjE3MDc5MjA5OTkxMTIsImV4cCI6MzAwLCJpc3MiOiJuY2hhaW4iLCJwcmVBdXRob3JpemVkQ29kZSI6ImExNmE0ZDIzLTZlZWEtNGE3MC1iZWU5LWE3MDRjYWY0NjQ1OSJ9.yqaNyNG_oiah3cb9ELU-ukKqxk_Utt5ntNeFuzC69w4LToRqHHWrMibyupluzKFxSiqEZ7lsKFta2mUdhPIO_Q"

token_type*string

String representing token type

Example: "bearer"

c_nonce*string

String containing a nonce to be used when creating a proof of possession of the key proof. When received, the Wallet MUST use this nonce value for its subsequent requests until the Credential Issuer provides a fresh nonce.

Example: "bea65ef2-ebd3-4006-b095-e5fbd6d96ccd"

c_nonce_expires_in*number

Number denoting the lifetime in seconds of the c_nonce.

Example: 30000

authorization_pending*boolean

Boolean indicating if the authorization is pending.

Example: false

interval*number

Example: 300000

Request

const response = await fetch('../public/{correlationId}/token', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "client_id": "nChain:vc-wallet",
      "grant_type": "urn:ietf:params:oauth:grant-type:pre-authorized_code",
      "pre-authorized_code": "ab407be3-d18f-4508-837e-6286329c1da2"
    }),
});
const data = await response.json();

Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksifQ.eyJpYXQiOjE3MDc5MjA5OTkxMTIsImV4cCI6MzAwLCJpc3MiOiJuY2hhaW4iLCJwcmVBdXRob3JpemVkQ29kZSI6ImExNmE0ZDIzLTZlZWEtNGE3MC1iZWU5LWE3MDRjYWY0NjQ1OSJ9.yqaNyNG_oiah3cb9ELU-ukKqxk_Utt5ntNeFuzC69w4LToRqHHWrMibyupluzKFxSiqEZ7lsKFta2mUdhPIO_Q",
  "token_type": "bearer",
  "c_nonce": "bea65ef2-ebd3-4006-b095-e5fbd6d96ccd",
  "c_nonce_expires_in": 30000,
  "authorization_pending": false,
  "interval": 300000
}

Create credential offer for the specified credential type.

Endpoint will return credential data that can be claimed which is transformed in QR code by web client, for wallet app to scan. User has to pass data in request body for which credential one wants to trigger issueance. In this example we will use Character credential. We want to create body with properties credentials which is an array of strings and has to contain CharacterCredential type as string. We also want to pass grants object with urn:ietf:params:oauth:grant-type:pre-authorized_code as key and object with pre-authorized_code which is a random id web client generates to later access status of issued credential, and user_pin_required property, which is set to false in this case. Last thing we want to pass is credentialDataSupplierInput object with properties for specified credential type. Those properties are written in JSON file in /dev/oid4vci_metadata directory in object credentialSubject. In this case we want to pass name and biography. If successful, the server returns a URI (in url encoded format) containing the credential offer and a boolean indicating if user pin is required (we set it to false).

POST../private/{correlationId}/webapp/credential-offers

Authorization

Path parameters

correlationId*string

The correlation ID defined on the server (nchain in our case).

Body

credentials*array of array

The type of the credential we want to issue.

grants*AgentCredentialOfferGrantsBodyDto (object)

credentialDataSupplierInput*object

The input for the credential data supplier. Depends on the credential type.

Response

Body

uri*string

URI containing the credential offer (decoded in example).

Example:

"openid-credential-offer://?credential_offer={\\\"grants\\\":{\\\"urn:ietf:params:oauth:grant-type:pre-authorized_code\\\":{\\\"pre-authorized_code\\\":\\\"sWoSmJM9vnD2yL3Ruot3ps\\\",\\\"user_pin_required\\\":false}},\\\"credentials\\\":[\\\"CharacterCredential\\\"],\\\"credential_issuer\\\":\\\"https://1c13-213-172-234-81.ngrok-free.app/nchain\\"

userPinRequired*boolean

Indicates if user pin is required.

Example: false

Request

const response = await fetch('../private/{correlationId}/webapp/credential-offers', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "credentials": [
        "EmailCredential"
      ],
      "grants": {
        "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
          "pre-authorized_code": "ab407be3-d18f-4508-837e-6286329c1da2",
          "user_pin_required": "false"
        }
      },
      "credentialDataSupplierInput": {
        "email": "john.doe@email.com"
      }
    }),
});
const data = await response.json();

Response

{
  "uri": "openid-credential-offer://?credential_offer={\\\"grants\\\":{\\\"urn:ietf:params:oauth:grant-type:pre-authorized_code\\\":{\\\"pre-authorized_code\\\":\\\"sWoSmJM9vnD2yL3Ruot3ps\\\",\\\"user_pin_required\\\":false}},\\\"credentials\\\":[\\\"CharacterCredential\\\"],\\\"credential_issuer\\\":\\\"https://1c13-213-172-234-81.ngrok-free.app/nchain\\",
  "userPinRequired": false
}

Check offer status.

Endpoint returns status of the credential offer that has been created (look at previous endpoint). User has to pass id of the offer in request body. Id is generated by web client when creating an offer (look at previous endpoint). If successful, the server returns an object with createdAt,lastUpdatedAt and status properties. createdAt is a timestamp indicating when the offer was created, lastUpdatedAt is a timestamp indicating the last update time of the offer and status is the status of the offer. status can be OFFER_CREATED, CREDENTIAL_ISSUED, ERROR

POST../private/{correlationId}/webapp/credential-offer-status

Authorization

Path parameters

correlationId*string

The correlation ID defined on the server (nchain in our case).

Body

id*string

The ID of the offer.

Response

Body

createdAt*number

Timestamp indicating when the offer was created.

Example: 1702632883012

lastUpdatedAt*number

Timestamp indicating the last update time of the offer.

Example: 1702632883012

status*enum

The status of the offer.

Example: "OFFER_CREATED"

OFFER_CREATEDOFFER_URI_RETRIEVEDACCESS_TOKEN_REQUESTEDACCESS_TOKEN_CREATEDCREDENTIAL_REQUEST_RECEIVEDCREDENTIAL_ISSUEDERROR

Request

const response = await fetch('../private/{correlationId}/webapp/credential-offer-status', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "id": "text"
    }),
});
const data = await response.json();

Response

{
  "createdAt": 1702632883012,
  "lastUpdatedAt": 1702632883012,
  "status": "OFFER_CREATED"
}

PreviousAgent NextWhat is a Verifier?

Last updated 14 days ago