credentials-config-service.yaml

openapi: 3.0.3
info:
  title: Credentials configuration service
  description: Provides and manages the scopes to be requested and the trust-anchors(trusted-issuers-list and trusted-participants-list) per service/credential.
  version: 0.0.1
tags:
  - name: service
paths:
  /service:
    post:
      tags:
        - service
      operationId: createService
      summary: Create a service with its credentials configuration
      description: Create a service with the given configuration. If no id is provided, the service will generate one.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Service'
      responses:
        '201':
          description: Successfully created the service.
          headers:
            Location:
              schema:
                type: string
                format: uri
                example: /service/packet-delivery-service
              description: Location of the created service
        '400':
          description: Invalid service provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Service with the given id already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    get:
      tags:
        - service
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageNumber'
      operationId: getServices
      summary: Return all services
      description: Return all services configured, with pagination.
      responses:
        '200':
          description: The service config.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Services'
        '400':
          description: Invalid query parameters provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /service/{id}:
    get:
      tags:
        - service
      parameters:
        - $ref: '#/components/parameters/Id'
      operationId: getService
      summary: Return the full service config by ID
      description: The service configuration, including all credentials and their trust anchors will be returned.
      responses:
        '200':
          description: The service config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '404':
          description: No such service exists.
    delete:
      tags:
        - service
      parameters:
        - $ref: '#/components/parameters/Id'
      operationId: deleteServiceById
      description: Delete a single service(and all its configurations) with the given id.
      summary: Delete the service
      responses:
        '204':
          description: Successfully deleted
        '404':
          description: No such service exists.
    put:
      tags:
        - service
      parameters:
        - $ref: '#/components/parameters/Id'
      summary: Update a single service
      description: Updates a single service by fully overriding it.
      operationId: updateService
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Service'
      responses:
        '200':
          description: Successfully updated the service.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '404':
          description: No such service exists.
        '400':
          description: Invalid service provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /service/{id}/scope:
    get:
      tags:
        - service
      parameters:
        - $ref: '#/components/parameters/Id'
        - $ref: '#/components/parameters/OidcScope'
      operationId: getScopeForService
      summary: Get the scope for the service
      description: Returns the scope(e.g. credential types to be requested) for the requested service
      responses:
        '200':
          description: The scopes to be requested for the service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scope'
        '404':
          description: No such service exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  parameters:
    Id:
      name: id
      in: path
      required: true
      schema:
        type: string
        example: packet-delivery-service
    OidcScope:
      name: oidcScope
      in: query
      required: false
      schema:
        type: string
        example: did_read
    PageSize:
      name: pageSize
      in: query
      schema:
        type: integer
        default: 100
        minimum: 1
    PageNumber:
      name: page
      in: query
      schema:
        type: integer
        default: 0
        minimum: 0
  schemas:
    Scope:
      type: array
      description: A list of credential-types to be requested
      items:
        type: string
      example:
        - VerifiableCredential
        - CustomerCredential
    Credential:
      type: object
      description: A credential-type with its trust configuration
      properties:
        type:
          type: string
          description: Type of the credential
          example: VerifiableCredential
        trustedParticipantsLists:
          type: array
          items:
            type: object
            description: Either a Url or a TrustedParticipantsList. For backward-compatibility,  plain url entries are interpreted as EBSI-Endpoints.
            example:
              - https://my-ebsi.list
              - type: gaia-x
                url: https://my-gaia-x.registry
        trustedIssuersLists:
          type: array
          description: |
            A list of (EBSI Trusted Issuers Registry compatible) endpoints to 
            retrieve the trusted issuers from. The attributes need to be formated
            to comply with the verifiers requirements.
          items:
            type: string
            format: url
            example: https://til-pdc.gaia-x.fiware.dev
        holderVerification:
          $ref: '#/components/schemas/HolderVerification'
        requireCompliance:
          type: boolean
          default: false
          description: Does the given credential require a compliancy credential
        jwtInclusion:
          $ref: '#/components/schemas/JwtInclusion'
      required:
        - type
    JwtInclusion:
      type: object
      description: Configuration for the credential to decide its inclusion into the JWT.
      properties:
        enabled:
          type: boolean
          default: true
          description: Should the given credential be included into the generated JWT
        fullInclusion:
          type: boolean
          default: false
          description: Should the complete credential be embedded
        claimsToInclude:
          type: array
          description: Claims to be included
          items:
            $ref: '#/components/schemas/Claim'
    Claim:
      type: object
      description: Claim of the a credential to be included in the JWT.
      properties:
        originalKey:
          type: string
          description: Key of the claim to be included. All objects under this key will be included unchanged.
        newKey:
          type: string
          description: Key of the claim to be used in the jwt. If not provided, the original one will be used.
      required:
        - originalKey
    TrustedParticipantsListEndpoint:
      type: object
      description: Endpoint of the trusted participants list and its type
      properties:
        type:
          type: string
          enum:
            - gaia-x
            - ebsi
        url:
          type: string
          format: url
          example: https://tir-pdc.gaia-x.fiware.dev
    HolderVerification:
      type: object
      description: Configuration of holder verification for the given credential type
      properties:
        enabled:
          type: boolean
          description: Should the holder verification be enabled
          default: false
        claim:
          type: string
          description: Name of the claim containing the holder id
          default: subject
      required:
        - enabled
        - claim
    ServiceScopesEntry:
      type: object
      properties:
        credentials:
          type: array
          description: Trust configuration for the credentials
          minItems: 1
          items:
            $ref: '#/components/schemas/Credential'
        presentationDefinition:
          $ref: '#/components/schemas/PresentationDefinition'
          nullable: true
        dcql:
          $ref: '#/components/schemas/DCQL'
          nullable: true
        flatClaims:
          type: boolean
          default: false
          description: When set, the claim are flatten to plain JWT-claims before beeing included, instead of keeping the credential/presentation structure, where the claims are under the key vc or vp
      required:
        - credentials
    Service:
      type: object
      description: Configuration of a service and its credentials
      properties:
        id:
          type: string
          description: Id of the service to be configured. If no id is provided, the service will generate one.
          example: packet-delivery-service
        defaultOidcScope:
          type: string
          description: Default OIDC scope to be used if none is specified
          example: default
        oidcScopes:
          type: object
          description: A specific OIDC scope for that service, specifying the necessary VC types (credentials)
          additionalProperties:
            $ref: '#/components/schemas/ServiceScopesEntry'
        authorizationType:
          type: string
          description: The authorization redirect to be created.
          default: FRONTEND_V2
          enum:
            - FRONTEND_V2
            - DEEPLINK
      required:
        - oidcScopes
        - defaultOidcScope
    Services:
      type: object
      description: The paginated list of services
      properties:
        total:
          type: integer
          description: Total number of services available
          example: 25
        pageNumber:
          type: integer
          description: Number of the page to be retrieved.
          example: 0
        pageSize:
          type: integer
          description: Size of the returend page, can be less than the requested depending on the available entries
          example: 10
        services:
          type: array
          description: The list of services
          items:
            $ref: '#/components/schemas/Service'
    DCQL:
      type: object
      description: JSON encoded query to request the credentials to be included in the presentation
      properties:
        credentials:
          type: array
          description: A non-empty array of Credential Queries that specify the requested Credentials.
          items:
            $ref: '#/components/schemas/CredentialQuery'
        credential_sets:
          type: array
          description: A non-empty array of Credential Set Queries that specifies additional constraints on which of the requested Credentials to return.
          items:
            $ref: '#/components/schemas/CredentialSetQuery'
      required:
        - credentials
    CredentialQuery:
      type: object
      description: A Credential Query is an object representing a request for a presentation of one or more matching Credentials
      properties:
        id:
          type: string
          description: A string identifying the Credential in the response and, if provided, the constraints in credential_sets. The value MUST be a non-empty string consisting of alphanumeric, underscore (_), or hyphen (-) characters. Within the Authorization Request, the same id MUST NOT be present more than once.
          example: my-credential-query-id
        format:
          type: string
          description: A string that specifies the format of the requested Credential.
          enum:
            - mso_mdoc
            - vc+sd-jwt
            - dc+sd-jwt
            - ldp_vc
            - jwt_vc_json
          example: jwt_vc_json
        multiple:
          type: boolean
          default: false
          description: A boolean which indicates whether multiple Credentials can be returned for this Credential Query. If omitted, the default value is false.
          example: false
        claims:
          type: array
          description: A non-empty array of objects  that specifies claims in the requested Credential. Verifiers MUST NOT point to the same claim more than once in a single query. Wallets SHOULD ignore such duplicate claim queries.
          items:
            $ref: '#/components/schemas/ClaimsQuery'
        meta:
          $ref: '#/components/schemas/MetaDataQuery'
        require_cryptographic_holder_binding:
          type: boolean
          default: true
          description: A boolean which indicates whether the Verifier requires a Cryptographic Holder Binding proof. The default value is true, i.e., a Verifiable Presentation with Cryptographic Holder Binding is required. If set to false, the Verifier accepts a Credential without Cryptographic Holder Binding proof.
          example: true
        claim_sets:
          type: array
          description: A non-empty array containing arrays of identifiers for elements in claims that specifies which combinations of claims for the Credential are requested.
          items:
            $ref: '#/components/schemas/ClaimSet'
        trusted_authorities:
          type: array
          description: A non-empty array of objects  that specifies expected authorities or trust frameworks that certify Issuers, that the Verifier will accept. Every Credential returned by the Wallet SHOULD match at least one of the conditions present in the corresponding trusted_authorities array if present.
          items:
            $ref: '#/components/schemas/TrustedAuthorityQuery'
    ClaimsQuery:
      type: object
      description: A query to specifies claims in the requested Credential.
      properties:
        id:
          type: string
          description: REQUIRED if claim_sets is present in the Credential Query; OPTIONAL otherwise. A string identifying the particular claim. The value MUST be a non-empty string consisting of alphanumeric, underscore (_), or hyphen (-) characters. Within the particular claims array, the same id MUST NOT be present more than once.
          example: my-claim-query-id
        path:
          type: array
          description:  The value MUST be a non-empty array representing a claims path pointer that specifies the path to a claim within the Credential. See https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#name-claims-path-pointer
          items:
            type: object
          example: ["path", "to", "claim"]
        values:
          type: array
          description: A non-empty array of strings, integers or boolean values that specifies the expected values of the claim. If the values property is present, the Wallet SHOULD return the claim only if the type and value of the claim both match exactly for at least one of the elements in the array.
          items:
            type: object
          example: ["supported-value-1", "supported-value-2"]
        intent_to_retain:
          type: boolean
          description: MDoc specific parameter, ignored for all other types. The flag can be set to inform that the reader wishes to keep(store) the data. In case of false, its data is only used to be dispalyed and verified.
          example: false
        namespace:
          type: string
          description: MDoc specific parameter, ignored for all other types. Refers to a namespace inside an mdoc.
          example: "org.iso.7367.1"
        claim_name:
          type: string
          description: MDoc specific parameter, ignored for all other types. Identifier for the data-element in the namespace.
          example: "first_name"
    MetaDataQuery:
      type: object
      description: Defines additional properties requested by the Verifier that apply to the metadata and validity data of the Credential. The properties of this object are defined per Credential Format. If empty, no specific constraints are placed on the metadata or validity of the requested Credential.
      properties:
        vct_values:
          type: array
          description: SD-JWT and JWT specific parameter. A non-empty array of strings that specifies allowed values for the type of the requested Verifiable Credential.The Wallet MAY return Credentials that inherit from any of the specified types, following the inheritance logic defined in https://datatracker.ietf.org/doc/html/draft-ietf-oauth-sd-jwt-vc-10
          items:
            type: string
        doctype_value:
          type: string
          description: Required for MDoc. String that specifies an allowed value for the doctype of the requested Verifiable Credential. It MUST be a valid doctype identifier as defined in https://www.iso.org/standard/69084.html
          example: "org.iso.7367.1.mVRC"
        type_values:
          type: array
          description: Required for ldp_vc. A non-empty array of string arrays. The Type value of the credential needs to be a subset of at least one of the string-arrays.
          items:
            type: array
            items:
              type: string
    ClaimSet:
      type: array
      description: An array contain identifiers of elements in the claims, that specifies wich combination of claims is requested
      items:
        type: string
      example: ["claim-id-a","claim-id-b"]
    TrustedAuthorityQuery:
      type: object
      description: An object representing information that helps to identify an authority or the trust framework that certifies Issuers. A Credential is identified as a match to a Trusted Authorities Query if it matches with one of the provided values in one of the provided types.
      properties:
        type:
          type: string
          description:  A string uniquely identifying the type of information about the issuer trust framework.
            - aki
            - etsi_tl
            - openid_federation
          example: "aki"
        values:
          type: array
          description: A non-empty array of strings, where each string (value) contains information specific to the used Trusted Authorities Query type that allows the identification of an issuer, a trust framework, or a federation that an issuer belongs to.
          items:
            type: string
          example: ["s9tIpPmhxdiuNkHMEWNpYim8S8Y"]
      required:
        - type
        - values
    CredentialSetQuery:
      type: object
      description: A Credential Set Query is an object representing a request for one or more Credentials to satisfy a particular use case with the Verifier.
      properties:
        options:
          type: array
          description: A non-empty array, where each value in the array is a list of Credential Query identifiers representing one set of Credentials that satisfies the use case. The value of each element in the options array is a non-empty array of identifiers which reference elements in credentials.
          items:
            type: array
            items:
              type: string
        required:
          type: boolean
          description: A boolean which indicates whether this set of Credentials is required to satisfy the particular use case at the Verifier.
          default: true
          example: true
        purpose:
          type: object
          description: A string, number or object specifying the purpose of the query. This specification does not define a specific structure or specific values for this property. The purpose is intended to be used by the Verifier to communicate the reason for the query to the Wallet. The Wallet MAY use this information to show the user the reason for the request.
          example: "Identification"
    PresentationDefinition:
      type: object
      description: Proofs required by the service - see https://identity.foundation/presentation-exchange/#presentation-definition
      properties:
        id:
          type: string
          description: Id of the definition
          example: "32f54163-7166-48f1-93d8-ff217bdb0653"
        name:
          type: string
          description: A human readable name for the definition
          example: My default service credentials
        purpose:
          type: string
          description: A string that describes the purpose for wich the definition should be used
          example: The service requires age and name of the requesting user.
        input_descriptors:
          type: array
          description: List of requested inputs for the presentation
          items:
            $ref: '#/components/schemas/InputDescriptor'
        format:
          $ref: '#/components/schemas/Format'
      required:
        - id
        - input_descriptors
    InputDescriptor:
      type: object
      properties:
        id:
          type: string
          description: Id of the descriptor
          example: "32f54163-7166-48f1-93d8-ff217bdb0653"
        name:
          type: string
          description: A human readable name for the definition
          example: User Age request
        purpose:
          type: string
          description: A string that describes the purpose for which the claim is requested
          example: Only users above a certain age should get service access
        constraints:
          $ref: '#/components/schemas/Constraints'
        format:
          $ref: '#/components/schemas/Format'
      required:
        - id
        - constraints
    Constraints:
      type: object
      properties:
        fields:
          type: array
          description: List of the requested claims
          items:
            $ref: '#/components/schemas/Field'
    Field:
      type: object
      properties:
        id:
          type: string
          description: Id of the field
          example: "32f54163-7166-48f1-93d8-ff217bdb0653"
        name:
          type: string
          description: A human readable name for the definition
          example: User Age request
        purpose:
          type: string
          description: A string that describes the purpose for which the claim is requested
          example: Only users above a certain age should get service access
        optional:
          type: boolean
          description: Defines if the described field is considered optional or not
        path:
          type: array
          description: An array of JsonPaths that selects the value from the input
          items:
            type: string
            example: "$.credentialSubject.dateOfBirth"
        filter:
          type: object
          description: Filter to be evaluated against the values returned from path evaluation
    Format:
      type: object
      additionalProperties: true
    ProblemDetails:
      type: object
      properties:
        type:
          description: An absolute URI that identifies the problem type. When dereferenced, it SHOULD provide human-readable documentation for the problem type.
          type: string
          format: uri
          ##default: about:blank
        title:
          description: A short summary of the problem type.
          type: string
          example: Internal Server Error
        status:
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          type: integer
          example: 500
        detail:
          description: A human readable explanation specific to this occurrence of the problem.
          type: string
          example: Connection timeout
        instance:
          description: An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
          type: string
          format: uri