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

HTTPcURLJavaScriptPython

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

OK

application/json

get

/.well-known/openid-credential-issuer

HTTPcURLJavaScriptPython

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

200

OK

{
  "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

OK

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

HTTPcURLJavaScriptPython

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

application/json

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

OK

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

post

/token

HTTPcURLJavaScriptPython

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"
}

Authorization Code FlowPre-authorization Code Flow

{
  "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

application/json

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

OK

application/json

400

Bad Request

application/json

post

/credential

HTTPcURLJavaScriptPython

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": "..."
  }
}

Key proof_type is cwtKey proof_type is jwtIETF SD-JWT VCISO mDL

{
  "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

application/json

Responses

200

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.

application/json

post

/batch_credential

HTTPcURLJavaScriptPython

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

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.

{
  "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

application/json

transaction_idstringRequired

String identifying a Deferred Issuance transaction.

Responses

200

OK

application/json

400

Bad Request

application/json

post

/deferred_credential

HTTPcURLJavaScriptPython

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

application/json

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

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.

post

/notification

HTTPcURLJavaScriptPython

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

OK

application/json

post

/verify/authorize

HTTPcURLJavaScriptPython

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

200

OK

{
  "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