Package com.authlete.common.dto

Class CredentialDeferredParseResponse

  • All Implemented Interfaces:
    Serializable
    public class CredentialDeferredParseResponse
extends ApiResponse
    Response from the /vci/deferred/parse API.

    The response from the Authlete API is a JSON object and can be mapped to this class. The API caller should retrieve the value of the action parameter from the API response and take one of the following actions accordingly.

    action = OK

    The action value OK means that the deferred credential request is valid. In this case, the implementation of the deferred credential endpoint should call the /vci/deferred/issue API in order to issue a verifiable credential, or return the issuance_pending error if the verifiable credential is not ready yet.

    The following is an example error response telling the request sender that the verifiable credential is not ready yet. 

     HTTP/1.1 400 Bad Request
 Content-Type: application/json
 Cache-Control: no-store

 {
   "error": "issuance_pending"
 }

    action = BAD_REQUEST

    The action value BAD_REQUEST means that the deferred credential request is invalid. In this case, the implementation of the deferred credential endpoint should return an error response to the request sender. The HTTP status code and the content type of the error response should be 400 and application/json, respectively. The value of the responseContent parameter can be used as the message body of the error response as it conforms to the specification of "Deferred Credential Error Response". 

     HTTP/1.1 400 Bad Request
 Content-Type: application/json
 Cache-Control: no-store

 (Put the value of the "responseContent" parameter here.)

    action = UNAUTHORIZED

    The action value UNAUTHORIZED means that the access token is invalid. In this case, the implementation of the deferred credential endpoint should return an error response to the request sender. The HTTP status code of the error response should be 401. The value of the responseContent parameter can be used as the value of the WWW-Authenticate HTTP header of the error response. 

     HTTP/1.1 401 Unauthorized
 WWW-Authenticate: (Put the value of the "responseContent" parameter here.)

    Note that the implementation of the deferred credential endpoint should call the /auth/introspection API to check whether the access token is valid BEFORE calling the /vci/deferred/parse API. The validation on the access token by the /vci/deferred/parse API is limited and not exhaustive. For example, the /vci/deferred/parse API does not check certificate binding (RFC 8705).

    action = FORBIDDEN

    The action value FORBIDDEN means that the use of the Authlete API is forbidden. In this case, the implementation of the deferred credential endpoint should return an error response to the request sender. The HTTP status code and the content type of the error response should be 403 and application/json, respectively. The value of the responseContent parameter can be used as the message body of the error response as it conforms to the specification of "Deferred Credential Error Response". 

     HTTP/1.1 403 Forbidden
 Content-Type: application/json
 Cache-Control: no-store

 (Put the value of the "responseContent" parameter here.)

    Note that this happens either when the verifiableCredentialsEnabled property of the service is false or when the Authlete server does not support the feature of "Verifiable Credentials". In either case, this "forbidden" issue should be solved before the service is deployed in a production environment.

    action = INTERNAL_SERVER_ERROR

    The action value INTERNAL_SERVER_ERROR means that something wrong happened on Authlete side. In this case, the implementation of the deferred credential endpoint should return an error response to the request sender. The HTTP status code and the content type of the error response should be 500 and application/json, respectively. The value of the responseContent parameter can be used as the message body of the error response as it conforms to the specification of "Deferred Credential Error Response". 

     HTTP/1.1 500 Internal Server Error
 Content-Type: application/json
 Cache-Control: no-store

 (Put the value of the "responseContent" parameter here.)

    Note that, however, in real production deployments, it may be better to return a vaguer error response instead of a bare one like above.

    Since:
    3.69, Authlete 3.0
    See Also:
    OpenID for Verifiable Credential Issuance, Serialized Form

    • Constructor Detail

      • CredentialDeferredParseResponse

        public CredentialDeferredParseResponse()

    • Method Detail

      • getAction

        public CredentialDeferredParseResponse.Action getAction()
        Get the next action that the deferred credential endpoint should take.
        Returns:
        The next action that the deferred credential endpoint should take.

      • getResponseContent

        public String getResponseContent()
        Get the content of the response that should be returned to the request sender. The format varies depending on the value of the action parameter.

        When the value of the action parameter is OK, the value of this parameter is null.

        When the value of the action parameter is UNAUTHORIZED, the value of this parameter is a string suitable as the value of the WWW-Authenticate HTTP header.

        In other error cases, the value of this parameter is JSON that conforms to the specification of "Deferred Credential Error Response".

        Returns:
        The content of the response that should be returned to the request sender.

      • setResponseContent

        public CredentialDeferredParseResponse setResponseContent​(String content)
        Set the content of the response that should be returned to the request sender. The format varies depending on the value of the action parameter.

        When the value of the action parameter is OK, the value of this parameter should be null.

        When the value of the action parameter is UNAUTHORIZED, the value of this parameter should be a string suitable as the value of the WWW-Authenticate HTTP header.

        In other error cases, the value of this parameter should be JSON that conforms to the specification of "Deferred Credential Error Response".

        Parameters:
        content - The content of the response that should be returned to the request sender.
        Returns:
        this object.

      • getInfo

        public CredentialRequestInfo getInfo()
        Get information about the credential request bound to the transaction ID.
        Returns:
        Information about the credential request bound to the transaction ID.

      • setInfo

        public CredentialDeferredParseResponse setInfo​(CredentialRequestInfo info)
        Set information about the credential request bound to the transaction ID.
        Parameters:
        info - Information about the credential request bound to the transaction ID.
        Returns:
        this object.