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 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 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.
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 encoded Credential Offer Object with the Credential Offer parameters. This MUST NOT be present when the credential_offer_uri parameter is present.
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.
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
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:
The language(s) in HTTP Accept-Language and Content-Language Headers MUST use the values defined in RFC3066.
OK
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.
The value set here determines the authorization processing flow. To use the authorization code flow, the value should be configured to "code".
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.
Valid OAuth 2.0 client identifier in the authorization server.
Redirection URI to which the response would be sent. This URI must match one of the redirection URI values during the client ID creation.
A challenge derived from the code_verifier, This is required if its a VC scoped request.
Redirection URI to which the response would be sent. This URI must match one of the redirection URI values during the client ID creation.
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.
No content
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.
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.
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.
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.
A JSON object containing the Verifier metadata values. It MUST be UTF-8 encoded.
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.
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).
Defined in RFC6749. The Wallet MAY allow Verifiers to request presentation of Verifiable Credentials by utilizing a pre-defined scope value.
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.
OK
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.
Authorization code grant type.
authorization_code for authorization code flowurn:ietf:params:oauth:grant-type:pre-authorized_code for pre-authorized code flowAuthorization code, sent as query param in the wallet's redirect URI. This parameter MUST only be used if the grant_type is authorization_code.
REQUIRED, if the "redirect_uri" parameter was included in the authorization request, and their values MUST be identical.
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.
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.
REQUIRED, if the client is not authenticating with the authorization server.
The Credential Endpoint issues a Credential as approved by the Holder upon presentation of a valid Access Token representing this approval.
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.
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.
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.
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.
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
OK
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.
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.
BEARER Token
String identifying a Deferred Issuance transaction.
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.
String received in the Credential Response or the Batch Credential Response.
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.credential_failure is to be used.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.
No content