8 Service APIs

This section provides a reference for APIs that should be implemented by this Building Block.

This section provides a reference for APIs that this Building Block should implement. The APIs defined here establish a blueprint for how the Building Block will interact with other building blocks. The Building Block may implement additional APIs, but the listed APIs define a minimal set of functionality that any implementation of this Building Block should provide.

The GovStack non-functional requirements document provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here. This section also guides how candidate products are tested and how GovStack validates a product's API against the API specifications defined here.

Consideration should be made of the GovStack cross cutting Security considerations at: https://specs.govstack.global/security-requirements

8.1 Credential Discovery

8.1.1. Credential Offer Endpoint

Credential Offer Endpoint

get

This endpoint is used by a credential issuer that is already interacting with a Holder who wishes to initiate a credential issuance. It is used to pass available information relevant for the credential issuance to ensure a convenient and secure process.

Query parameters

credential_offerstringOptional

JSON encoded Credential Offer Object with the Credential Offer parameters. This MUST NOT be present when the credential_offer_uri parameter is present.

credential_offer_uristringOptional

String that is a URL using the https scheme referencing a resource containing a JSON object with the Credential Offer parameters. This MUST NOT be present when the credential_offer parameter is present.

Responses

200

The Wallet does not create a response for Credential Offer Endpoint. The UX control stays with the Wallet after completion of the process.

get

/credential_offer

GET /credential_offer HTTP/1.1
Host: govstack.sandbox.com
Accept: */*

200

The Wallet does not create a response for Credential Offer Endpoint. The UX control stays with the Wallet after completion of the process.

No content

8.1.2. Credential Issuer Metadata

Credential Issuer Metadata

get

The Credential Issuer Metadata contains information on the Credential Issuer's technical capabilities, supported Credentials, and (internationalized) display information.

The Credential Issuer's configuration can be retrieved using the Credential Issuer Identifier. A Credential Issuer is identified by a case sensitive URL using the https scheme that contains scheme, host and, optionally, port number and path components, but no query or fragment components which is know as Credential Issuer Identifier.

The Credential Issuer's configuration can be retrieved using the Credential Issuer Identifier. Credential Issuers publishing metadata MUST make a JSON document available at the path formed by concatenating the string /.well-known/openid-credential-issuer to the Credential Issuer Identifier. If the Credential Issuer value contains a path component, any terminating / MUST be removed before appending /.well-known/openid-credential-issuer.

The communication with the Credential Issuer Metadata Endpoint MUST utilize TLS.

The Wallet is RECOMMENDED to send an Accept-Language Header in the HTTP GET request to indicate the language(s) preferred for display. It is up to the Credential Issuer whether to:

send a subset the metadata containing internationalized display data for one or all of the requested languages and indicate returned languages using the HTTP Content-Language Header, or
ignore the Accept-Language Header and send all supported languages or any chosen subset.

The language(s) in HTTP Accept-Language and Content-Language Headers MUST use the values defined in RFC3066.

Responses

200

application/json

credential_issuerstringRequired

Credential Issuer's identifier which is identified by a case sensitive URL using the HTTPS scheme that contains scheme, host and, optionally, port number and path components, but no query or fragment components.

authorization_serversstring[]Optional

Array of strings, where each string is an identifier of the OAuth 2.0 Authorization Server (as defined in RFC8414) the Credential Issuer relies on for authorization.

If this parameter is omitted, then the Credential Issuer is also acting as the Authorization Server, i.e., the Credential Issuer's identifier is used to obtain the Authorization Server metadata. The actual OAuth 2.0 Authorization Server metadata is obtained from the oauth-authorization-server well-known location.

When there are multiple entries in the array, the Wallet may be able to determine which Authorization Server to use by querying the metadata; for example, by examining the grant_types_supported values, the Wallet can filter the server to use based on the grant type it plans to use.

When the Wallet is using authorization_server parameter in the Credential Offer as a hint to determine which authorization server to use out of multiple, the Wallet MUST NOT proceed with the flow if the authorization_server Credential Offer parameter value does not match any of the entries in the authorization_servers array.

credential_endpointstringRequired

URL of the Credential Issuer's Credential Endpoint. This URL MUST use the HTTPS scheme and MAY contain port, path, and query parameter components.

batch_credential_endpointstringOptional

URL of the Credential Issuer's Batch Credential Endpoint. This URL MUST use the https scheme and MAY contain port, path, and query parameter components. If omitted, the Credential Issuer does not support the Batch Credential Endpoint.

deferred_credential_endpointstringOptional

URL of the Credential Issuer's Deferred Credential Endpoint. This URL MUST use the HTTPS scheme and MAY contain port, path, and query parameter components. If omitted, it is assumed that the Credential Issuer does not support the Deferred Credential Endpoint.

notification_endpointstringOptional

URL of the Credential Issuer's Notification Endpoint. This URL MUST use the HTTPS scheme and MAY contain port, path, and query parameter components. If omitted, the Credential Issuer does not support the Notification Endpoint.

credential_identifiers_supportedbooleanOptional

Boolean value specifying whether the Credential Issuer supports returning credential_identifiers parameter in the authorization_details Token Response parameter, with true indicating support. If omitted, the default value is false.

signed_metadatastringOptional

String that is a signed JWT. This JWT contains Credential Issuer metadata parameters as claims. The signed metadata MUST be secured using JSON Web Signature (JWS) RFC7515 and MUST contain an iat(Issued At) claim, an iss(Issuer) claim denoting the party attesting to the claims in the signed metadata, and sub(Subject) claim matching the Credential Issuer identifier. If the Wallet supports signed metadata, metadata values conveyed in the signed JWT MUST take precedence over the corresponding values conveyed using plain JSON elements. If the Credential Issuer wants to enforce use of signed metadata, it omits the respective metadata parameters from the unsigned part of the Credential Issuer metadata. A signed_metadata metadata value MUST NOT appear as a claim in the JWT. The Wallet MUST establish trust in the signer of the metadata, and obtain the keys to validate the signature before processing the metadata.

get

/.well-known/openid-credential-issuer

GET /.well-known/openid-credential-issuer HTTP/1.1
Host: govstack.sandbox.com
Accept: */*

200

{
  "credential_issuer": "text",
  "authorization_servers": [
    "text"
  ],
  "credential_endpoint": "text",
  "batch_credential_endpoint": "text",
  "deferred_credential_endpoint": "text",
  "notification_endpoint": "text",
  "credential_response_encryption": {
    "alg_values_supported": [
      "text"
    ],
    "enc_values_supported": [
      "text"
    ],
    "encryption_required": true
  },
  "credential_identifiers_supported": true,
  "signed_metadata": "text",
  "display": [
    {
      "name": "text",
      "locale": "text",
      "logo": {
        "uri": "text",
        "alt_text": "text"
      }
    }
  ],
  "credential_configurations_supported": {
    "named_key": {
      "format": "text",
      "scope": "text",
      "cryptographic_binding_methods_supported": [
        "text"
      ],
      "credential_signing_alg_values_supported": [
        "text"
      ],
      "proof_types_supported": {
        "jwt": {
          "proof_signing_alg_values_supported": [
            "text"
          ]
        }
      },
      "display": [
        {
          "name": "text",
          "locale": "text",
          "logo": {
            "url": "text",
            "alt_text": "text"
          },
          "description": "text",
          "background_color": "text",
          "background_image": {
            "uri": "text"
          },
          "text_color": "text"
        }
      ],
      "credential_definition": {
        "type": [
          "text"
        ],
        "credentialSubject": {
          "attribute_name": {
            "mandatory": true,
            "value_type": "text",
            "display": [
              {
                "name": "text",
                "locale": "text"
              }
            ]
          }
        }
      }
    }
  }
}

8.2. Credential Issuance

8.2.1. Authorization Endpoint

Authorization Endpoint for Issuance

get

The authorization endpoint is used to interact with the Issuer's authorization server and obtain an authorization grant. The authorization server MUST first verify the identity of the Holder. The way in which the authorization server authenticates the Holder's (e.g., username and password login, session cookies) is beyond the scope of this specification.

This endpoint could respond with a basic HTML page to load a JS application in the browser. In case of mobile wallet, it would load the JS application in the mobile browser.

Query parameters

response_typestringRequired

The value set here determines the authorization processing flow. To use the authorization code flow, the value should be configured to "code".

scopestringRequired

Specifies what access privileges are being requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. OpenID Connect requests MUST contain the OpenID scope value.

client_idstringRequired

Valid OAuth 2.0 client identifier in the authorization server.

redirect_uristringRequired

Redirection URI to which the response would be sent. This URI must match one of the redirection URI values during the client ID creation.

code_challengestringOptional

A challenge derived from the code_verifier, This is required if its a VC scoped request.

code_challenge_methodstringOptional

The method of challenge this will be 'plain' or 'S256' depending on whether the challenge is the plain verifier string or the SHA256 hash of the string.

authorization_detailsstringOptional

MUST be used to convey the details about the Credentials the Wallet wants to obtain when sent from the issuer to wallet. For details on authorization details click here.

Body

Responses

200

Loads JS application, and validates the provided query parameters using oauth-details endpoint.

Once the Holder is successfully authenticated, the authorization_code is shared in the query parameter of the redirect_uri mentioned in the authorization request.

302

Found

If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the Holder of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.

The authorization server informs the client by adding the following parameters to the query component of the redirection URI using the application/x-www-form-urlencoded format.

Example: https://govstack.sandbox.com?error=invalid_request&error_description=Unsupported%20response_type%20value

invalid_request: The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unauthorized_client: The client is not authorized to request an authorization code using this method.
access_denied: The resource owner or authorization server denied the request.
unsupported_response_type: The authorization server does not support obtaining an authorization code using this method.
invalid_scope: The requested scope is invalid, unknown, or malformed.
server_error: The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)
temporarily_unavailable: The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.)

get

/authorize

GET /authorize?response_type=text&scope=text&client_id=text&redirect_uri=text HTTP/1.1
Host: govstack.sandbox.com
Accept: */*

No content

8.2.2. Token Endpoint

Token Endpoint

post

The Token Endpoint issues an Access Token and, optionally, a Refresh Token in exchange for the Authorization Code that Client obtained in a successful Authorization Response. It is used in the same manner as defined in RFC6749.

Body

grant_typeundefined · enumRequired

Authorization code grant type.

authorization_code for authorization code flow
urn:ietf:params:oauth:grant-type:pre-authorized_code for pre-authorized code flow

Possible values:

codestringOptional

Authorization code, sent as query param in the wallet's redirect URI. This parameter MUST only be used if the grant_type is authorization_code.

redirect_uristringOptional

REQUIRED, if the "redirect_uri" parameter was included in the authorization request, and their values MUST be identical.

pre-authorized_codestringOptional

The code representing the authorization to obtain Credentials of a certain type. This parameter MUST be present if the grant_type is urn:ietf:params:oauth:grant-type:pre-authorized_code.

tx_codestringOptional

String value containing a Transaction Code. This parameter MUST only be used if the grant_type is urn:ietf:params:oauth:grant-type:pre-authorized_code.

client_idstringOptional

REQUIRED, if the client is not authenticating with the authorization server.

Responses

200

application/json

access_tokenstringRequired

The access token issued by the issuer's authorization server.

token_typeundefined · enumRequired

The access token type provides the wallet with the information required to successfully utilize the access token to make a protected resource request (along with type-specific attributes). The wallet MUST NOT use an access token if it does not understand the token type.

Possible values:

expires_inintegerOptional

The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. If omitted, the authorization server SHOULD provide the expiration time via other means or document the default value.

c_noncestringOptional

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.

c_nonce_expires_inintegerOptional

Number denoting the lifetime in seconds of the c_nonce.

authorization_detailsobject[]Optional

When authorization_details parameter is used to request issuance of a certain credential type. It MUST NOT be used otherwise. It is an array of objects, as defined in RFC9396.

The authorization details assigned to the access token issued in a token response are determined by the authorization_details parameter of the corresponding token request. If the client does not specify the authorization_details token request parameters, the Authorization Server determines the resulting authorization_details at its discretion.

statestringOptional

REQUIRED if the "state" parameter was present in the client authorization request. The exact value received from the client.

400

Bad Request

application/json

401

Unauthorized

application/json

post

/token

POST /token HTTP/1.1
Host: govstack.sandbox.com
Content-Type: application/json
Accept: */*
Content-Length: 118

{
  "grant_type": "authorization_code",
  "code": "SplxlOBeZQQYbYS6WxSbIA",
  "redirect_uri": "https://wallet.example.org/wallet"
}

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp..sHQ",
  "token_type": "bearer",
  "expires_in": 86400,
  "c_nonce": "tZignsnFbp",
  "c_nonce_expires_in": 86400,
  "authorization_details": [
    {
      "type": "openid_credential",
      "credential_configuration_id": "UniversityDegreeCredential",
      "credential_identifiers": [
        "CivilEngineeringDegree-2023",
        "ElectricalEngineeringDegree-2023"
      ]
    }
  ]
}

8.2.3. Credential Endpoint

Credential Endpoint

post

The Credential Endpoint issues a Credential as approved by the Holder upon presentation of a valid Access Token representing this approval.

Body

formatstringOptional

REQUIRED when the credential_identifiers parameter was not returned from the Token Response. It MUST NOT be used otherwise. It is a String that determines the format of the Credential to be issued, which may determine the type and any other information related to the Credential to be issued. When this parameter is used, the credential_identifier Credential Request parameter MUST NOT be present.

credential_identifierstringOptional

REQUIRED when credential_identifiers parameter was returned from the Token Response. It MUST NOT be used otherwise. It is a String that identifies a Credential that is being requested to be issued.

doctypestringOptional

This is a string identifying the Credential type, as defined in ISO.18013-5.

It is required when the credential format identifier is set as mso_mdoc.

vctstringOptional

This is required when the format parameter is present in the Credential Meta Information. It is a string designating the type of a Credential, as defined in I-D.ietf-oauth-sd-jwt-vc. This claim contains the type value of the Credential that the Wallet requests the Credential Issuer to issue.

Responses

200

application/json

credentialstringOptional

Contains issued Credential. It MUST be present when transaction_id is not returned. It MAY be a string or an object, depending on the Credential format.

transaction_idstringOptional

String identifying a Deferred Issuance transaction. This claim is contained in the response if the Credential Issuer was unable to immediately issue the Credential. The value is subsequently used to obtain the respective Credential with the Deferred Credential Endpoint.

It MUST be present when the credential parameter is not returned.

It MUST be invalidated after the Credential for which it was meant has been obtained by the Wallet.

c_noncestringOptional

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

c_nonce_expires_inintegerOptional

Number denoting the lifetime in seconds of the c_nonce.

notification_idstringOptional

A string identifying an issued Credential that the Wallet includes in the Notification Request. This parameter MUST NOT be present if credential parameter is not present.

400

Bad Request

application/json

post

/credential

POST /credential HTTP/1.1
Host: govstack.sandbox.com
Content-Type: application/json
Accept: */*
Content-Length: 97

{
  "format": "mso_mdoc",
  "doc_type": "org.iso.18013.5.1.mDL",
  "proof": {
    "proof_type": "cwt",
    "cwt": "..."
  }
}

{
  "credential": "LUpixVCWJk0eOt4CXQe1NXK....WZwmhmn9OQp6YxX0a2L",
  "c_nonce": "fGFF7UkhLa",
  "c_nonce_expires_in": 86400
}

8.2.4. Batch Credential Endpoint

Batch Credential Endpoint

post

The Batch Credential Endpoint issues multiple Credentials in one Batch Credential Response as approved by the End-User upon presentation of a valid Access Token representing this approval. Support for this endpoint is OPTIONAL.

Communication with the Batch Credential Endpoint MUST utilize TLS.

The Client can request issuance of multiple Credentials of certain types and formats in one Batch Credential Request. This includes Credentials of the same type and multiple formats, different types and one format, or both

Body

Responses

200

A successful Batch Credential Response MUST contain all the requested Credentials. The Batch Credential Response MUST be sent as a JSON object using the application/json media type.

application/json

c_noncestringOptional

c_nonce_expires_inintegerOptional

Number denoting the lifetime in seconds of the c_nonce.

post

/batch_credential

POST /batch_credential HTTP/1.1
Host: govstack.sandbox.com
Content-Type: application/json
Accept: */*
Content-Length: 360

{
  "credential_requests": [
    {
      "format": "text",
      "proof": {
        "proof_type": "text",
        "cwt": "text",
        "jwt": "text",
        "ldp_vp": "text"
      },
      "credential_identifier": "text",
      "doc_type": "text",
      "credential_response_encryption": {
        "jwk": "text",
        "alg": "text",
        "enc": "text"
      },
      "doctype": "text",
      "vct": "text",
      "claims": {
        "mandatory": true,
        "value_type": "text",
        "display": [
          {
            "name": "text",
            "locale": "text"
          }
        ]
      }
    }
  ]
}

200

A successful Batch Credential Response MUST contain all the requested Credentials. The Batch Credential Response MUST be sent as a JSON object using the application/json media type.

{
  "credential_responses": [
    {
      "credential": "eyJraWQiOiJkaWQ6ZXhhbXBsZTpl...C_aZKPxgihac0aW9EkL1nOzM"
    },
    {
      "credential": "YXNkZnNhZGZkamZqZGFza23....29tZTIzMjMyMzIzMjMy"
    }
  ],
  "c_nonce": "fGFF7UkhLa",
  "c_nonce_expires_in": 86400
}

8.2.5. Deffered Credential Endpoint

Deferred Credential

post

This endpoint is used to issue a Credential previously requested at the Credential Endpoint in cases where the Credential Issuer was not able to immediately issue this Credential.

The Wallet must present to the Deferred Endpoint an Access Token that is valid for the issuance of the Credential previously requested at the Credential Endpoint.

Header parameters

AuthorizationstringRequired

BEARER Token

Body

transaction_idstringRequired

String identifying a Deferred Issuance transaction.

Responses

200

application/json

credentialstringOptional

Contains issued Credential. It MUST be present when transaction_id is not returned. It MAY be a string or an object, depending on the Credential format.

transaction_idstringOptional

It MUST be present when the credential parameter is not returned.

It MUST be invalidated after the Credential for which it was meant has been obtained by the Wallet.

c_noncestringOptional

c_nonce_expires_inintegerOptional

Number denoting the lifetime in seconds of the c_nonce.

400

Bad Request

application/json

post

/deferred_credential

POST /deferred_credential HTTP/1.1
Host: govstack.sandbox.com
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 31

{
  "transaction_id": "8xLOxBtZp8"
}

{
  "credential": "text",
  "transaction_id": "text",
  "c_nonce": "text",
  "c_nonce_expires_in": 1
}

8.2.6. Notification Endpoint

Notification Endpoint

post

This endpoint is used by the Wallet to notify the Credential Issuer of certain events for issued Credentials. These events enable the Credential Issuer to take subsequent actions after issuance. The Credential Issuer needs to return one or more notification_id parameters in the Credential Response or the Batch Credential Response for the Wallet to be able to use this Endpoint. Support for this endpoint is OPTIONAL. The Issuer cannot assume that a notification will be sent for every issued credential since the use of this Endpoint is not mandatory for the Wallet.

A Credential Issuer that requires a request to the Notification Endpoint MUST ensure the Access Token issued by the Authorization Server is valid at the Notification Endpoint.

The notification from the Wallet is idempotent. When the Credential Issuer receives multiple identical calls from the Wallet for the same notification_id, it returns success. Due to the network errors, there are no guarantees that a Credential Issuer will receive a notification within a certain time period or at all.

Communication with the Notification Endpoint MUST utilize TLS.

Body

notification_idstringRequired

String received in the Credential Response or the Batch Credential Response.

eventundefined · enumRequired

Type of the notification event. It MUST be a case sensitive string whose value is either credential_accepted, credential_failure, or credential_deleted.

credential_accepted is to be used when the Credential was successfully stored in the Wallet, with or without user action.
credential_deleted is to be used when the unsuccessful Credential issuance was caused by a user action.
In all other unsuccessful cases, credential_failure is to be used.

Possible values:

event_descriptionstringOptional

Human-readable ASCII text providing additional information, used to assist the Credential Issuer developer in understanding the event that occurred. Values for the event_description parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.

Responses

204

No Content

When the Credential Issuer has successfully received the Notification Request from the Wallet, it MUST respond with an HTTP status code in the 2xx range. Use of the HTTP status code 204 (No Content) is RECOMMENDED.

400

Bad Request

application/json

2XX

Success

post

/notification

POST /notification HTTP/1.1
Host: govstack.sandbox.com
Content-Type: application/json
Accept: */*
Content-Length: 83

{
  "notification_id": "text",
  "event": "credential_accepted",
  "event_description": "text"
}

No content

8.3 Credential Presentations

8.3.1 Authorization Request

Authorization Endpoint for Presentation

post

The Authorization Request in this specification is based on RFC6749 and aligns with the security recommendations from I-D.ietf-oauth-security-topics. The Verifier can send an Authorization Request either by value or by reference using a JWT-Secured Authorization Request (JAR) as defined in RFC9101. To support cases where the Wallet needs to communicate its technical capabilities, the Authorization Request can include a request_uri_method parameter with the value post. This allows the Wallet to make an HTTP POST request to the Verifier’s request_uri endpoint, providing information about its capabilities.

The Verifier can specify the requirements for requested credentials using the presentation_definition and presentation_definition_uri parameters, containing a Presentation Definition JSON object per DIF.PresentationExchange. The Wallet is expected to process this JSON object and select suitable Verifiable Credentials based on the evaluation criteria defined. Additionally, the Verifier can use the client_id_scheme and client_metadata parameters to communicate a Client Identifier Scheme and related metadata, enabling the Wallet to interpret the Client Identifier, authenticate, and authorize accordingly. These parameters provide flexibility for deploying different mechanisms for Client metadata validation.

Query parameters

presentation_definitionstringRequired

A string containing a Presentation Definition JSON object. This parameter MUST be present when presentation_definition_uri parameter, or a scope value representing a Presentation Definition is not present.

presentation_definition_uristringRequired

A string containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. This parameter MUST be present when presentation_definition parameter, or a scope value representing a Presentation Definition is not present.

client_id_schemestringOptional

A string identifying the scheme of the value in the client_id Authorization Request parameter (Client Identifier scheme). The client_id_scheme parameter namespaces the respective Client Identifier. If an Authorization Request uses the client_id_scheme parameter, the Wallet MUST interpret the Client Identifier of the Verifier in the context of the Client Identifier scheme. If the parameter is not present, the Wallet MUST behave as specified in RFC6749. If the same Client Identifier is used with different Client Identifier schemes, those occurrences MUST be treated as different Verifiers. Note that the Verifier needs to determine which Client Identifier schemes the Wallet supports prior to sending the Authorization Request in order to choose a supported scheme.

client_metadatastringOptional

A JSON object containing the Verifier metadata values. It MUST be UTF-8 encoded.

request_uri_methodstringOptional

A string determining the HTTP method to be used when the request_uri parameter is included in the same request. Two case-sensitive valid values are defined in this specification: get and post. If request_uri_method value is get, the Wallet MUST send the request to retrieve the Request Object using the HTTP GET method, i.e., as defined in RFC9101. If request_uri_method value is post, a supporting Wallet MUST send the request using the HTTP POST method. If the request_uri_method parameter is not present, the Wallet MUST process the request_uri parameter as defined in RFC9101. Wallets not supporting the post method will send a GET request to the Request URI (default behavior as defined in RFC9101). request_uri_method parameter MUST NOT be present if a request_uri parameter is not present.

noncestringRequired

It is used to securely bind the Verifiable Presentation(s) provided by the Wallet to the particular transaction. Values MUST only contain ASCII URL safe characters (uppercase and lowercase letters, decimal digits, hyphen, period, underscore, and tilde).

scopestringOptional

Defined in RFC6749. The Wallet MAY allow Verifiers to request presentation of Verifiable Credentials by utilizing a pre-defined scope value.

response_modestringOptional

This parameter is used (through the new Response Mode direct_post) to ask the Wallet to send the response to the Verifier via an HTTPS connection. It is also used to request signing and encrypting. If the parameter is not present, the default value is fragment.

Responses

200

application/json

vp_tokenstringOptional

post

/verify/authorize

POST /verify/authorize?presentation_definition=text&presentation_definition_uri=text&nonce=text HTTP/1.1
Host: govstack.sandbox.com
Accept: */*

200

{
  "vp_token": "eyJhb...YMetA",
  "presentation_submission": {
    "definition_id": "example_jwt_vc",
    "id": "example_jwt_vc_presentation_submission",
    "descriptor_map": [
      {
        "id": "id_credential",
        "path": "$",
        "format": "jwt_vp",
        "path_nested": {
          "path": "$.vp.verifiableCredential[0]",
          "format": "jwt_vc"
        }
      }
    ]
  }
}

The wallet-building block would be making egress calls for,

An authentication system for initiating authentication of the holder
The consent system for capturing the holder's consent

Previous7 Data Structures Next9 Internal Workflows

Last updated 1 month ago

hashtag8.1 Credential Discovery

hashtag8.1.1. Credential Offer Endpoint

hashtagCredential Offer Endpoint

hashtag8.1.2. Credential Issuer Metadata

hashtagCredential Issuer Metadata

hashtag8.2. Credential Issuance

hashtag8.2.1. Authorization Endpoint

hashtagAuthorization Endpoint for Issuance

hashtag8.2.2. Token Endpoint

hashtagToken Endpoint

hashtag8.2.3. Credential Endpoint

hashtagCredential Endpoint

hashtag8.2.4. Batch Credential Endpoint

hashtagBatch Credential Endpoint

hashtag8.2.5. Deffered Credential Endpoint

hashtagDeferred Credential

hashtag8.2.6. Notification Endpoint

hashtagNotification Endpoint

hashtag8.3 Credential Presentations

hashtag8.3.1 Authorization Request

hashtagAuthorization Endpoint for Presentation

8.1 Credential Discovery

8.1.1. Credential Offer Endpoint

Credential Offer Endpoint

8.1.2. Credential Issuer Metadata

Credential Issuer Metadata

8.2. Credential Issuance

8.2.1. Authorization Endpoint

Authorization Endpoint for Issuance

8.2.2. Token Endpoint

Token Endpoint

8.2.3. Credential Endpoint

Credential Endpoint

8.2.4. Batch Credential Endpoint

Batch Credential Endpoint

8.2.5. Deffered Credential Endpoint

Deferred Credential

8.2.6. Notification Endpoint

Notification Endpoint

8.3 Credential Presentations

8.3.1 Authorization Request

Authorization Endpoint for Presentation