# 8 Service APIs 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](https://govstack.gitbook.io/specification/architecture-and-nonfunctional-requirements/6-onboarding) 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: ## **8.1 Credential Discovery** ### 8.1.1. Credential Offer Endpoint ## Credential Offer Endpoint > 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. ```json {"openapi":"3.1.0","info":{"title":"Wallet Building Block","version":"1.0"},"servers":[{"url":"https://govstack.sandbox.com","description":""}],"paths":{"/credential_offer":{"get":{"summary":"Credential Offer Endpoint","tags":[],"responses":{"200":{"description":"The Wallet does not create a response for Credential Offer Endpoint. The UX control stays with the Wallet after completion of the process.\n","content":{}}},"operationId":"credential-offer","description":"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.","parameters":[{"schema":{"type":"string"},"in":"query","name":"credential_offer","description":"JSON encoded Credential Offer Object with the Credential Offer parameters. This MUST NOT be present when the `credential_offer_uri` parameter is present."},{"schema":{"type":"string"},"in":"query","name":"credential_offer_uri","description":"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."}]}}}} ``` ### 8.1.2. Credential Issuer Metadata ## Credential Issuer Metadata > 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]\().
```json {"openapi":"3.1.0","info":{"title":"Wallet Building Block","version":"1.0"},"servers":[{"url":"https://govstack.sandbox.com","description":""}],"paths":{"/.well-known/openid-credential-issuer":{"get":{"summary":"Credential Issuer Metadata","tags":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["credential_issuer","credential_endpoint"],"properties":{"credential_issuer":{"type":"string","description":"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_servers":{"type":"array","description":"Array of strings, where each string is an identifier of the OAuth 2.0 Authorization Server (as defined in [RFC8414](https://www.rfc-editor.org/rfc/rfc8414.html)) the Credential Issuer relies on for authorization. \n\nIf 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. \n\nWhen 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. \n\nWhen 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.","items":{"type":"string"}},"credential_endpoint":{"type":"string","description":"URL of the Credential Issuer's [Credential Endpoint](wallet-bb.yaml/paths/~1credential/post). This URL MUST use the HTTPS scheme and MAY contain port, path, and query parameter components."},"batch_credential_endpoint":{"type":"string","description":"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_endpoint":{"type":"string","description":"URL of the Credential Issuer's [Deferred Credential Endpoint](wallet-bb.yaml/paths/~1deferred_credential). 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_endpoint":{"type":"string","description":"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_response_encryption":{"type":"object","description":"This object contains information about whether the Credential Issuer supports encryption of the Credential Response on top of TLS (Transport Layer Security).","required":["alg_values_supported","enc_values_supported","encryption_required"],"properties":{"alg_values_supported":{"type":"array","description":"Array containing a list of the JWE [RFC7516](https://www.rfc-editor.org/rfc/rfc7516.html) encryption algorithms (alg values) [RFC7518](https://www.rfc-editor.org/rfc/rfc7518.html) supported by the Credential and Batch Credential Endpoint to encode the Credential or Batch Credential Response in a JWT [RFC7519](https://www.rfc-editor.org/rfc/rfc7519.html).","items":{"type":"string"}},"enc_values_supported":{"type":"array","description":"Array containing a list of the JWE [RFC7516](https://www.rfc-editor.org/rfc/rfc7516.html) encryption algorithms (enc values) [RFC7518](https://www.rfc-editor.org/rfc/rfc7518.html) supported by the Credential and Batch Credential Endpoint to encode the Credential or Batch Credential Response in a JWT [RFC7519](https://www.rfc-editor.org/rfc/rfc7519.html).","items":{"type":"string"}},"encryption_required":{"type":"boolean","description":"Boolean value specifying whether the Credential Issuer requires the additional encryption on top of Transport Layer Security for the Credential Response. \n* If the value is `true`, the Credential Issuer requires encryption for every Credential Response and therefore the Wallet MUST provide encryption keys in the Credential Request. \n* If the value is `false`, the Wallet MAY chose whether it provides encryption keys or not.\n\nIt is recommended that the value is kept as true and every Credential Response SHOULD be encrypted on top of Transport Layer Security."}}},"credential_identifiers_supported":{"type":"boolean","description":"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_metadata":{"type":"string","description":"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](https://www.rfc-editor.org/rfc/rfc7515.html) 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."},"display":{"type":"array","description":"This is an array of objects, where each object contains display properties of a Credential Issuer for a certain language.","items":{"type":"object","properties":{"name":{"type":"string","description":"String value of a display name for the Credential Issuer.\n"},"locale":{"type":"string","description":"String value that identifies the language of this object represented as a language tag taken from values defined in BCP47 [RFC5646](https://datatracker.ietf.org/doc/html/rfc5646). There MUST be only one object for each language identifier."},"logo":{"type":"object","description":"Object with information about the logo of the Credential Issuer.","required":["uri"],"properties":{"uri":{"type":"string","description":"String value that contains a URI where the Wallet can obtain the logo of the Credential Issuer. The Wallet needs to determine the scheme, since the URI value could use the `https:` scheme, the `data:` scheme, etc.\n"},"alt_text":{"type":"string","description":"String value of the alternative text for the logo image."}}}}}},"credential_configurations_supported":{"type":"object","description":"Object that describes specifics of the Credential that the Credential Issuer supports issuance of. This object contains a list of name/value pairs, where each name is a unique identifier of the supported Credential being described. This identifier is used in the Credential Offer endpoint to communicate to the Wallet which Credential is being offered. The value is an object that contains metadata about a specific Credential.","properties":{"named_key":{"$ref":"#/components/schemas/Credential-Metadata"}}}}}}}}},"operationId":"get-issuer-well-known","description":"The Credential Issuer Metadata contains information on the Credential Issuer's technical capabilities, supported Credentials, and (internationalized) display information.\n\nThe 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**.\n\nThe 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`.\n\nThe communication with the Credential Issuer Metadata Endpoint MUST utilize TLS.\n\nThe 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:\n\n* 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\n* ignore the Accept-Language Header and send all supported languages or any chosen subset.\n\nThe language(s) in HTTP Accept-Language and Content-Language Headers MUST use the values defined in [RFC3066](https://www.rfc-editor.org/rfc/rfc3066.html).\n"}}},"components":{"schemas":{"Credential-Metadata":{"type":"object","title":"Credential Metadata","required":["credential_definition"],"properties":{"format":{"type":"string","description":"A JSON string identifying the format of this Credential, i.e., `jwt_vc_json` or `ldp_vc`. Depending on the format value, the object contains further elements defining the type and (optionally) particular claims the Credential MAY contain and information about how to display the Credential."},"scope":{"type":"string","description":"A JSON string identifying the scope value that this Credential Issuer supports for this particular Credential. The value can be the same across multiple `credential_configurations_supported` objects. The Authorization Server MUST be able to uniquely identify the Credential Issuer based on the scope value. The Wallet can use this value in the [Authorization Request](wallet-bb.yaml/paths/~1authorize/get). Scope values in this Credential Issuer metadata MAY duplicate those in the `scopes_supported` parameter of the Authorization Server."},"cryptographic_binding_methods_supported":{"type":"array","description":"Array of case sensitive strings that identify the representation of the cryptographic key material that the issued Credential is bound to. Support for keys in JWK format [RFC7517](https://www.rfc-editor.org/rfc/rfc7517.html) is indicated by the value `jwk`. Support for keys expressed as a COSE Key object [RFC8152](https://www.rfc-editor.org/rfc/rfc8152.html) (for example, used in [ISO.18013-5](https://www.iso.org/standard/69084.html)) is indicated by the value `cose_key`. When the Cryptographic Binding Method is a DID, valid values are a did: prefix followed by a method-name using a syntax as defined in Section 3.1 of [DID-Core](https://www.w3.org/TR/did-core/), but without a :and method-specific-id. For example, support for the DID method with a method-name \"example\" would be represented by did:example.","items":{"type":"string"}},"credential_signing_alg_values_supported":{"type":"array","description":"Array of case sensitive strings that identify the algorithms that the Issuer uses to sign the issued Credential.","items":{"type":"string"}},"proof_types_supported":{"type":"object","description":"Object that describes specifics of the key proof(s) that the Credential Issuer supports. This object contains a list of name/value pairs, where each name is a unique identifier of the supported proof type(s). A few of the valid values are defined below, while other values MAY be used. This identifier is also used by the Wallet in the [Credential Request](wallet-bb.yaml/paths/~1credential/post).\n\nBelow are a few `proof_type` supported for the `proof_type` property:\n* `jwt`: A JWT [RFC7519](https://www.rfc-editor.org/rfc/rfc7519.html) is used as proof of possession. When proof_type is jwt, a proof object MUST include a jwt claim containing a JWT.\n* `cwt`: A CWT [RFC8392](https://www.rfc-editor.org/rfc/rfc8392.html) is used as proof of possession. When proof_type is cwt, a proof object MUST include a cwt claim containing a CWT.\n* `ldp_vp`: A W3C Verifiable Presentation object signed using the Data Integrity Proof as defined in [VC_DATA_2.0](https://www.w3.org/TR/vc-data-model-2.0/) or [VC_DATA](https://www.w3.org/TR/vc-data-model/), and where the proof of possession MUST be done in accordance with [VC_Data_Integrity](https://w3c.github.io/vc-data-integrity/). When `proof_type` is set to `ldp_vp`, the proof object MUST include a `ldp_vp` claim containing a [W3C Verifiable Presentation](https://www.w3.org/TR/vc-data-model-2.0/#presentations-0).","properties":{"jwt":{"type":"object","required":["proof_signing_alg_values_supported"],"properties":{"proof_signing_alg_values_supported":{"type":"array","description":"Array of case sensitive strings that identify the algorithms that the Issuer supports for this proof type. The Wallet uses one of them to sign the proof. Algorithm names used are determined by the key proof types.","items":{"type":"string"}}}}}},"display":{"type":"array","description":"Array of objects, where each object contains the display properties of the supported Credential for a certain language. \n\nBelow is a non-exhaustive list of parameters that MAY be included.","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"String value of a display name for the Credential."},"locale":{"type":"string","description":"String value that identifies the language of this object represented as a language tag taken from values defined in BCP47 [RFC5646](https://www.rfc-editor.org/rfc/rfc5646.html). Multiple display objects MAY be included for separate languages. There MUST be only one object for each language identifier."},"logo":{"type":"object","description":"Object with information about the logo of the Credential.","required":["url"],"properties":{"url":{"type":"string","description":"String value that contains a URI where the Wallet can obtain the logo of the Credential from the Credential Issuer. The Wallet needs to determine the scheme, since the URI value could use the https: scheme, the data: scheme, etc."},"alt_text":{"type":"string","description":"String value of the alternative text for the logo image."}}},"description":{"type":"string","description":"String value of a description of the Credential.\n"},"background_color":{"type":"string","description":"String value of a background color of the Credential represented as numerical color values defined in CSS Color Module Level 37 [CSS-Color](https://www.w3.org/TR/css-color-3/)."},"background_image":{"type":"object","description":"Object with information about the background image of the Credential.","required":["uri"],"properties":{"uri":{"type":"string","description":"String value that contains a URI where the Wallet can obtain the background image of the Credential from the Credential Issuer. The Wallet needs to determine the scheme, since the URI value could use the `https:` scheme, the `data:` scheme, etc."}}},"text_color":{"type":"string","description":"String value of a text color of the Credential represented as numerical color values defined in CSS Color Module Level 37 [CSS-Color](https://www.w3.org/TR/css-color-3/)."}}}},"credential_definition":{"type":"object","description":"Object containing the detailed description of the Credential type.","required":["type"],"properties":{"type":{"type":"array","description":"Array designating the types a certain Credential type supports, according to [VC_DATA](https://www.w3.org/TR/vc-data-model/).","items":{"type":"string"}},"credentialSubject":{"type":"object","description":"Object containing a list of name/value pairs, where each name identifies a claim offered in the Credential. The value can be another such object (nested data structures), or an array of such objects. To express the specifics about the claim, the most deeply nested value MAY be an object that includes the following parameters defined by this specification.","properties":{"attribute_name":{"type":"object","properties":{"mandatory":{"type":"boolean","description":"Boolean which, when set to `true`, indicates that the Credential Issuer will always include this claim in the issued Credential. If set to `false`, the claim is not included in the issued Credential if the wallet did not request the inclusion of the claim, and/or if the Credential Issuer chose to not include the claim. If the mandatory parameter is omitted, the default value is `false`."},"value_type":{"type":"string","description":"String value determining the type of value of the claim. Valid values defined by this specification are string, number, and image media types such as image/jpeg as defined in [IANA media type registry for images](https://www.iana.org/assignments/media-types/media-types.xhtml#image). Other values MAY also be used."},"display":{"type":"array","description":"Array of objects, where each object contains display properties of a certain claim in the Credential for a certain language.","items":{"type":"object","properties":{"name":{"type":"string","description":"String value of a display name for the claim."},"locale":{"type":"string","description":"String value that identifies language of this object represented as language tag values defined in BCP47 [RFC5646](https://www.rfc-editor.org/rfc/rfc5646.html). There MUST be only one object for each language identifier."}}}}}}}}}}},"description":"The `credential_configurations_supported` object in the response of [Credential Issuer Metadata Endpoint] describes the specifics of the Credential that the Credential Issuer supports issuance of. \n\nThis object contains a list of name/value pairs, where each name is a unique identifier of the supported Credential being described. \n\nThis identifier is used in the [Credential Offer](wallet-bb.yaml/components/schemas/Credential-Offer) to communicate to the Wallet which Credential is being offered while the value is an object that contains metadata about a specific Credential.\n\nHere, the parameters of the credential metadata object are defined."}}}} ``` ## **8.2. Credential Issuance** ### 8.2.1. Authorization Endpoint ## Authorization Endpoint for Issuance > 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.
```json {"openapi":"3.1.0","info":{"title":"Wallet Building Block","version":"1.0"},"servers":[{"url":"https://govstack.sandbox.com","description":""}],"paths":{"/authorize":{"get":{"summary":"Authorization Endpoint for Issuance","tags":[],"responses":{"200":{"description":"OK\n\nLoads JS application, and validates the provided query parameters using oauth-details endpoint.\n\nOnce the Holder is successfully authenticated, the `authorization_code` is shared in the query parameter of the `redirect_uri` mentioned in the authorization request.","content":{}},"302":{"description":"Found\n\nIf the request fails due to a missing, invalid, or mismatching\n redirection URI, or if the client identifier is missing or invalid,\n the authorization server SHOULD inform the Holder of the\n error and MUST NOT automatically redirect the user-agent to the\n invalid redirection URI.\n\nThe authorization server informs the client by adding the following\n parameters to the query component of the redirection URI using the\n `application/x-www-form-urlencoded` format.\n\nExample:\nhttps://govstack.sandbox.com?error=invalid_request&error_description=Unsupported%20response_type%20value\n\n\n\n* `invalid_request`:\n The request is missing a required parameter, includes an\n invalid parameter value, includes a parameter more than\n once, or is otherwise malformed.\n* `unauthorized_client`:\n The client is not authorized to request an authorization\n code using this method.\n* `access_denied`:\n The resource owner or authorization server denied the\n request.\n* `unsupported_response_type`:\n The authorization server does not support obtaining an\n authorization code using this method.\n* `invalid_scope`:\n The requested scope is invalid, unknown, or malformed.\n* `server_error`:\n The authorization server encountered an unexpected\n condition that prevented it from fulfilling the request.\n (This error code is needed because a 500 Internal Server\n Error HTTP status code cannot be returned to the client\n via an HTTP redirect.)\n* `temporarily_unavailable`:\n The authorization server is currently unable to handle\n the request due to a temporary overloading or maintenance\n of the server. (This error code is needed because a 503\n Service Unavailable HTTP status code cannot be returned\n to the client via an HTTP redirect.)\n","content":{}}},"operationId":"authorize","description":"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.\n\nThis 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.\n","parameters":[{"schema":{"type":"string"},"in":"query","name":"response_type","description":"The value set here determines the authorization processing flow. To use the authorization code flow, the value should be configured to \"code\".","required":true},{"schema":{"type":"string"},"in":"query","name":"scope","description":"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.","required":true},{"schema":{"type":"string"},"in":"query","name":"client_id","description":"Valid OAuth 2.0 client identifier in the authorization server.","required":true},{"schema":{"type":"string"},"in":"query","name":"redirect_uri","description":"Redirection URI to which the response would be sent. This URI must match one of the redirection URI values during the client ID creation.","required":true},{"schema":{"type":"string"},"in":"query","name":"code_challenge","description":"A challenge derived from the code_verifier, This is required if its a VC scoped request."},{"schema":{"type":"string"},"in":"query","name":"code_challenge_method","description":"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."},{"schema":{"type":"string"},"in":"query","name":"authorization_details","description":"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](wallet-bb.yaml/components/schemas/Authorization-Details)."}],"requestBody":{"content":{}}}}}} ``` ### 8.2.2. Token Endpoint ## Token Endpoint > 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]\(). ```json {"openapi":"3.1.0","info":{"title":"Wallet Building Block","version":"1.0"},"servers":[{"url":"https://govstack.sandbox.com","description":""}],"paths":{"/token":{"post":{"summary":"Token Endpoint","operationId":"token","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["access_token","token_type"],"properties":{"access_token":{"type":"string","description":"The access token issued by the issuer's authorization server."},"token_type":{"description":"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.","enum":["bearer"]},"expires_in":{"type":"integer","description":"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_nonce":{"type":"string","description":"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_in":{"type":"integer","description":"Number denoting the lifetime in seconds of the c_nonce."},"authorization_details":{"type":"array","description":"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](https://www.rfc-editor.org/rfc/rfc9396.html).\n\nThe 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.","items":{"type":"object"}},"state":{"type":"string","description":"REQUIRED if the \"state\" parameter was present in the client authorization request. The exact value received from the client."}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"enum":["invalid_request","invalid_grant","invalid_client","unauthorized_client","unsupported_grant_type","invalid_scope"],"description":"A single ASCII error code from the following:\n* `invalid_request`:\n * The Authorization Server does not expect a Transaction Code in the Pre-Authorized Code Flow but the Client provides a Transaction Code.\n * The Authorization Server expects a Transaction Code in the Pre-Authorized Code Flow but the Client does not provide a Transaction Code.\n* `invalid_grant`:\n * The Authorization Server expects a Transaction Code in the Pre-Authorized Code Flow but the Client provides the wrong Transaction Code.\n * The End-User provides the wrong Pre-Authorized Code or the Pre-Authorized Code has expired.\n* `invalid_client`:\n * The Client tried to send a Token Request with a Pre-Authorized Code without a Client ID but the Authorization Server does not support anonymous access.\n* `unsupported_grant_type`:\n * The authorization grant type is not supported by the authorization server.\n* `invalid_scope`:\n * The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the Issuer.\n"},"error_description":{"type":"string","description":"Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the \"error_description\" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E."},"error_uri":{"type":"string","description":"A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the \"error_uri\" parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E."}}}}}},"401":{"description":"Unauthorized\n","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"enum":["unauthorized_client"],"description":"* `unauthorized_client`:\n * The authenticated client is not authorized to use this authorization grant type."},"error_description":{"type":"string","description":"Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the \"error_description\" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E."},"error_uri":{"type":"string","description":"A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the \"error_uri\" parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E."}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["grant_type"],"properties":{"grant_type":{"description":"Authorization code grant type.\n* `authorization_code` for authorization code flow\n* `urn:ietf:params:oauth:grant-type:pre-authorized_code` for pre-authorized code flow","enum":["authorization_code","urn:ietf:params:oauth:grant-type:pre-authorized_code"]},"code":{"type":"string","description":"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_uri":{"type":"string","description":"REQUIRED, if the \"redirect_uri\" parameter was included in the authorization request, and their values MUST be identical.\n"},"pre-authorized_code":{"type":"string","description":"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_code":{"type":"string","description":"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_id":{"type":"string","description":"REQUIRED, if the client is not authenticating with the authorization server."}}}}},"description":""},"description":"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](https://www.rfc-editor.org/rfc/rfc6749.html)."}}}} ``` ### 8.2.3. Credential Endpoint ## Credential Endpoint > The Credential Endpoint issues a Credential as approved by the Holder upon presentation of a valid Access Token representing this approval. ```json {"openapi":"3.1.0","info":{"title":"Wallet Building Block","version":"1.0"},"servers":[{"url":"https://govstack.sandbox.com","description":""}],"paths":{"/credential":{"post":{"summary":"Credential Endpoint","operationId":"credential","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"credential":{"type":"string","description":"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_id":{"type":"string","description":"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. \n\nIt MUST be present when the credential parameter is not returned. \n\nIt MUST be invalidated after the Credential for which it was meant has been obtained by the Wallet."},"c_nonce":{"type":"string","description":"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_in":{"type":"integer","description":"Number denoting the lifetime in seconds of the `c_nonce`."},"notification_id":{"type":"string","description":"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":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"enum":[" invalid_credential_request","unsupported_credential_type","unsupported_credential_format","invalid_proof","invalid_encryption_parameters"],"description":"A single ASCII error code from the following:\n* `invalid_credential_request`: The Credential Request is missing a required parameter, includes an unsupported parameter or parameter value, repeats the same parameter, or is otherwise malformed.\n* `unsupported_credential_type`: Requested Credential type is not supported.\n* `unsupported_credential_format`: Requested Credential format is not supported.\n* `invalid_proof`: The proof in the Credential Request is invalid. The proof field is not present or the provided key proof is invalid or not bound to a nonce provided by the Credential Issuer.\n* `invalid_encryption_parameters`: This error occurs when the encryption parameters in the Credential Request are either invalid or missing. In the latter case, it indicates that the Credential Issuer requires the Credential Response to be sent encrypted, but the Credential Request does not contain the necessary encryption parameters."},"error_description":{"type":"string","description":"Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the \"error_description\" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E."},"error_uri":{"type":"string","description":"A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the \"error_uri\" parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E."}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"format":{"description":"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.\n","type":"string"},"proof":{"type":"object","description":"Object containing the proof of possession of the cryptographic key material the issued Credential would be bound to. The proof object is REQUIRED if the `proof_types_supported` parameter is non-empty and present in the `credential_configurations_supported` parameter of the Issuer metadata for the requested Credential. ","required":["proof_type"],"properties":{"proof_type":{"type":"string","description":"String denoting the key proof type. The value of this parameter determines other parameters in the key proof object and its respective processing rules."}}},"credential_identifier":{"type":"string","description":"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."},"credential_response_encryption":{"type":"object","description":"Object containing information for encrypting the Credential Response. If this request element is not present, the corresponding credential response returned is not encrypted.","required":["jwk","alg","enc"],"properties":{"jwk":{"type":"object","description":"Object containing a single public key as a JWK used for encrypting the Credential Response."},"alg":{"type":"string","description":"JWE alg algorithm for encrypting Credential Responses."},"enc":{"type":"string","description":"JWE enc algorithm for encrypting Credential Responses."}}},"doctype":{"type":"string","description":"This is a string identifying the Credential type, as defined in [ISO.18013-5](https://www.iso.org/standard/69084.html).\n\nIt is required when the credential format identifier is set as `mso_mdoc`. "},"vct":{"type":"string","description":"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](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-sd-jwt-vc-01). This claim contains the type value of the Credential that the Wallet requests the Credential Issuer to issue."},"claims":{"type":"object","description":"Object containing a list of name/value pairs, where the name is a certain namespace as defined in [ISO.18013-5](https://www.iso.org/standard/69084.html) (or any profile of it), and the value is an object. This object also contains a list of name/value pairs, where the name is a claim name value that is defined in the respective namespace and is offered in the Credential.","properties":{"mandatory":{"type":"boolean","description":"Boolean which, when set to `true`, indicates that the Credential Issuer will always include this claim in the issued Credential. If set to `false`, the claim is not included in the issued Credential if the wallet did not request the inclusion of the claim, and/or if the Credential Issuer chose to not include the claim. If the `mandatory` parameter is omitted, the default value is `false`."},"value_type":{"type":"string","description":"String value determining the type of value of the claim. Valid values defined by this specification are string, number, and image media types such as image/jpeg as defined in IANA media type registry for images (https://www.iana.org/assignments/media-types/media-types.xhtml#image). Other values MAY also be used.\n"},"display":{"type":"array","description":"Array of objects, where each object contains display properties of a certain claim in the Credential for a certain language. ","items":{"type":"object","properties":{"name":{"type":"string","description":"String value of a display name for the claim."},"locale":{"type":"string","description":"String value that identifies language of this object represented as language tag values defined in BCP47 [RFC5646](https://www.rfc-editor.org/rfc/rfc5646.html). There MUST be only one object for each language identifier."}}}}}}}}}},"description":"A Client makes a Credential Request to the Credential Endpoint by sending the following parameters in the entity-body of an HTTP POST request using the `application/json` media type."},"description":"The Credential Endpoint issues a Credential as approved by the Holder upon presentation of a valid Access Token representing this approval."}}}} ``` ### 8.2.4. Batch Credential Endpoint ## Batch Credential Endpoint > 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 ```json {"openapi":"3.1.0","info":{"title":"Wallet Building Block","version":"1.0"},"servers":[{"url":"https://govstack.sandbox.com","description":""}],"paths":{"/batch_credential":{"post":{"summary":"Batch Credential Endpoint","tags":[],"responses":{"200":{"description":"OK\n\nA 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.\n","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"credential_responses":{"type":"array","description":"Array that contains Credential Response objects as defined in [Credential Endpoint](), and/or Deferred Credential Response objects as defined in [Deferred Credentila Endpoint](). Every entry of the array corresponds to the Credential Request object at the same array index in the `credential_requests` parameter of the Batch Credential Request.","items":{"type":"object","properties":{"transaction_id":{"type":"string"},"credential":{"type":"string"}}}},"c_nonce":{"type":"string","description":"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_in":{"type":"integer","description":"Number denoting the lifetime in seconds of the c_nonce."}}}}}}},"operationId":"post-batch_credential","description":"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.\n\nCommunication with the Batch Credential Endpoint MUST utilize TLS.\n\nThe 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","requestBody":{"description":"The Batch Credential Endpoint allows a Client to send multiple Credential Request objects to request the issuance of multiple Credentials at once. A Batch Credential Request MUST be sent as a JSON object using the application/json media type.","content":{"application/json":{"schema":{"type":"object","required":["credential_requests"],"properties":{"credential_requests":{"type":"array","description":"Array that contains Credential Request objects.","items":{"$ref":"#/components/schemas/Credential-Request"}}}}}}}}}},"components":{"schemas":{"Credential-Request":{"type":"object","title":"Credential Request","properties":{"format":{"type":"string","description":"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.\n"},"proof":{"type":"object","description":"Object containing the proof of possession of the cryptographic key material the issued Credential would be bound to. The proof object is REQUIRED if the `proof_types_supported` parameter is non-empty and present in the `credential_configurations_supported` parameter of the Issuer metadata for the requested Credential. ","required":["proof_type"],"properties":{"proof_type":{"type":"string","description":"String denoting the key proof type. The value of this parameter determines other parameters in the key proof object and its respective processing rules.\n\nBelow are a few `proof_type` supported for the `proof_type` property:\n* `jwt`: A JWT [RFC7519](https://www.rfc-editor.org/rfc/rfc7519.html) is used as proof of possession. When `proof_type` is `jwt`, a proof object MUST include a `jwt` claim containing a JWT.\n* `cwt`: A CWT [RFC8392](https://www.rfc-editor.org/rfc/rfc8392.html) is used as proof of possession. When `proof_type` is `cwt`, a proof object MUST include a `cwt` claim containing a CWT.\n* `ldp_vp`: A W3C Verifiable Presentation object signed using the Data Integrity Proof as defined in [VC_DATA_2.0](https://www.w3.org/TR/vc-data-model-2.0/) or [VC_DATA](https://www.w3.org/TR/vc-data-model/), and where the proof of possession MUST be done in accordance with [VC_Data_Integrity](https://w3c.github.io/vc-data-integrity/). When `proof_type` is set to `ldp_vp`, the proof object MUST include a `ldp_vp` claim containing a [W3C Verifiable Presentation](https://www.w3.org/TR/vc-data-model-2.0/#presentations-0)."},"cwt":{"type":"string","description":"A CWT [RFC8392](https://www.rfc-editor.org/rfc/rfc8392.html) is used as proof of possession. When `proof_type` is `cwt`, a proof object MUST include a `cwt` claim containing a CWT."},"jwt":{"type":"string","description":"A JWT [RFC7519](https://www.rfc-editor.org/rfc/rfc7519.html) is used as proof of possession. When proof_type is `jwt`, a proof object MUST include a jwt claim containing a JWT."},"ldp_vp":{"type":"string","description":"A W3C Verifiable Presentation object signed using the Data Integrity Proof as defined in [VC_DATA_2.0](https://www.w3.org/TR/vc-data-model-2.0/) or [VC_DATA](https://www.w3.org/TR/vc-data-model/), and where the proof of possession MUST be done in accordance with [VC_Data_Integrity](https://w3c.github.io/vc-data-integrity/). When `proof_type` is set to `ldp_vp`, the proof object MUST include a `ldp_vp` claim containing a [W3C Verifiable Presentation](https://www.w3.org/TR/vc-data-model-2.0/#presentations-0)."}}},"credential_identifier":{"type":"string","description":"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."},"doc_type":{"type":"string","description":"This is a string identifying the Credential type, as defined in [ISO.18013-5](https://www.iso.org/standard/69084.html).\n\nIt is required when the credential format identifier is set as `mso_mdoc`. "},"credential_response_encryption":{"type":"object","description":"Object containing information for encrypting the Credential Response. If this request element is not present, the corresponding credential response returned is not encrypted.","required":["jwk","alg","enc"],"properties":{"jwk":{"type":"string","description":"Object containing a single public key as a JWK used for encrypting the Credential Response."},"alg":{"type":"string","description":"JWE alg algorithm for encrypting Credential Responses."},"enc":{"type":"string","description":"JWE enc algorithm for encrypting Credential Responses."}}},"doctype":{"type":"string","description":"This is a string identifying the Credential type, as defined in [ISO.18013-5](https://www.iso.org/standard/69084.html).\n\nIt is required when the credential format identifier is set as `mso_mdoc`."},"vct":{"type":"string","description":"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](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-sd-jwt-vc-01). This claim contains the type value of the Credential that the Wallet requests the Credential Issuer to issue."},"claims":{"type":"object","description":"Object containing a list of name/value pairs, where the name is a certain namespace as defined in [ISO.18013-5](https://www.iso.org/standard/69084.html) (or any profile of it), and the value is an object. This object also contains a list of name/value pairs, where the name is a claim name value that is defined in the respective namespace and is offered in the Credential.","properties":{"mandatory":{"type":"boolean","description":"Boolean which, when set to `true`, indicates that the Credential Issuer will always include this claim in the issued Credential. If set to `false`, the claim is not included in the issued Credential if the wallet did not request the inclusion of the claim, and/or if the Credential Issuer chose to not include the claim. If the `mandatory` parameter is omitted, the default value is `false`."},"value_type":{"type":"string","description":"String value determining the type of value of the claim. Valid values defined by this specification are string, number, and image media types such as image/jpeg as defined in IANA media type registry for images (https://www.iana.org/assignments/media-types/media-types.xhtml#image). Other values MAY also be used.\n"},"display":{"type":"array","description":"Array of objects, where each object contains display properties of a certain claim in the Credential for a certain language. ","items":{"type":"object","properties":{"name":{"type":"string","description":"String value of a display name for the claim."},"locale":{"type":"string","description":"String value that identifies language of this object represented as language tag values defined in BCP47 [RFC5646](https://www.rfc-editor.org/rfc/rfc5646.html). There MUST be only one object for each language identifier."}}}}}}}}}}} ``` ### 8.2.5. Deffered Credential Endpoint ## Deferred Credential > 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. ```json {"openapi":"3.1.0","info":{"title":"Wallet Building Block","version":"1.0"},"servers":[{"url":"https://govstack.sandbox.com","description":""}],"paths":{"/deferred_credential":{"post":{"summary":"Deferred Credential","tags":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"credential":{"type":"string","description":"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_id":{"type":"string","description":"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. \n\nIt MUST be present when the credential parameter is not returned. \n\nIt MUST be invalidated after the Credential for which it was meant has been obtained by the Wallet."},"c_nonce":{"type":"string","description":"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_in":{"type":"integer","description":"Number denoting the lifetime in seconds of the `c_nonce`."}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}},"operationId":"deferred-credential","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["transaction_id"],"properties":{"transaction_id":{"type":"string","description":"String identifying a Deferred Issuance transaction."}}}}}},"description":"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.\n\nThe 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.","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","description":"BEARER Token","required":true}]}}}} ``` ### 8.2.6. Notification Endpoint ## Notification Endpoint > 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. ```json {"openapi":"3.1.0","info":{"title":"Wallet Building Block","version":"1.0"},"servers":[{"url":"https://govstack.sandbox.com","description":""}],"paths":{"/notification":{"post":{"summary":"Notification Endpoint","tags":[],"responses":{"204":{"description":"No Content\n\nWhen 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":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"The value of the error parameter SHOULD be one of the following ASCII error codes:\n* `invalid_notification_id`: The notification_id in the Notification Request was invalid.\n* `invalid_notification_request`: The Notification Request is missing a required parameter, includes an unsupported parameter or parameter value, repeats the same parameter, or is otherwise malformed.","enum":["invalid_notification_id","invalid_notification_request"]}}}}}},"2XX":{"description":"Success\n\nWhen 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."}},"operationId":"post-notification","requestBody":{"description":"The Wallet sends an HTTP POST request to the Notification Endpoint with the following parameters in the entity-body and using the application/json media type. If the Wallet supports the Notification Endpoint, the Wallet MAY send one or more Notification Requests per Credential issued.","content":{"application/json":{"schema":{"type":"object","required":["notification_id","event"],"properties":{"notification_id":{"type":"string","description":"String received in the Credential Response or the Batch Credential Response."},"event":{"description":"Type of the notification event. It MUST be a case sensitive string whose value is either `credential_accepted`, `credential_failure`, or `credential_deleted`. \n\n* `credential_accepted` is to be used when the Credential was successfully stored in the Wallet, with or without user action. \n* `credential_deleted` is to be used when the unsuccessful Credential issuance was caused by a user action. \n* In all other unsuccessful cases, `credential_failure` is to be used.","enum":["credential_accepted","credential_failure","credential_deleted"]},"event_description":{"type":"string","description":"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.\n"}}}}}},"description":"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.\n\nA 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.\n\nThe 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.\n\nCommunication with the Notification Endpoint MUST utilize TLS."}}}} ``` ## **8.3 Credential Presentations** ### 8.3.1 Authorization Request ## Authorization Endpoint for Presentation > 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. ```json {"openapi":"3.1.0","info":{"title":"Wallet Building Block","version":"1.0"},"servers":[{"url":"https://govstack.sandbox.com","description":""}],"paths":{"/verify/authorize":{"post":{"summary":"Authorization Endpoint for Presentation","tags":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"vp_token":{"type":"string"},"presentation_submission":{"type":"object","properties":{"definition_id":{"type":"string"},"id":{"type":"string"},"descriptor_map":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"format":{"type":"string"},"path_nested":{"type":"object","properties":{"path":{"type":"string"},"format":{"type":"string"}}}}}}}}}}}}}},"operationId":"get-verify-authorize","parameters":[{"schema":{"type":"string"},"in":"query","name":"presentation_definition","description":"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.","required":true},{"schema":{"type":"string"},"in":"query","name":"presentation_definition_uri","description":"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.","required":true},{"schema":{"type":"string"},"in":"query","name":"client_id_scheme","description":"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](https://www.rfc-editor.org/rfc/rfc6749.html). 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."},{"schema":{"type":"string"},"in":"query","name":"client_metadata","description":"A JSON object containing the Verifier metadata values. It MUST be UTF-8 encoded."},{"schema":{"type":"string"},"in":"query","name":"request_uri_method","description":"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](https://www.rfc-editor.org/rfc/rfc9101.html). 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](https://www.rfc-editor.org/rfc/rfc9101.html). Wallets not supporting the post method will send a GET request to the Request URI (default behavior as defined in [RFC9101](https://www.rfc-editor.org/rfc/rfc9101.html)). request_uri_method parameter MUST NOT be present if a request_uri parameter is not present."},{"schema":{"type":"string"},"in":"query","name":"nonce","description":"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).","required":true},{"schema":{"type":"string"},"in":"query","name":"scope","description":"Defined in [RFC6749](https://www.rfc-editor.org/rfc/rfc6749.html). The Wallet MAY allow Verifiers to request presentation of Verifiable Credentials by utilizing a pre-defined scope value."},{"schema":{"type":"string"},"in":"query","name":"response_mode","description":"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."}],"description":"The Authorization Request in this specification is based on [RFC6749](https://www.rfc-editor.org/rfc/rfc6749.html) and aligns with the security recommendations from [I-D.ietf-oauth-security-topics](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics-29). The Verifier can send an Authorization Request either by value or by reference using a JWT-Secured Authorization Request (JAR) as defined in [RFC9101](https://www.rfc-editor.org/rfc/rfc9101.html). 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.\n\nThe 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](https://identity.foundation/presentation-exchange/spec/v2.0.0/). 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."}}}} ``` {% hint style="info" %} 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 {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://specs.govstack.global/wallet/1.1.0/8-service-apis.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.