AccountManager.yaml

openapi: 3.0.3
info:
  title: I_AccountManager_Service
  description:  The KIM Account Manager is managed via this interface.
  #  The “utf-8” character set must be supported for all operations.
  version: 2.4.0
### 2.4.0
  # - changed servers url, for compatibility
  # - remove parameter appTags and newStAKowner
  # - remove error code 424
### 2.3.3
  # - new parameter newStAKowner (new owner Standard Anwendungskennzeichen)
  # - new error code 424, when default Anwendungskennzeichen will be lost
### 2.3.2
  # - changed servers -url for KIM 1.5.2 compatibility
  # - changed path (/account) for KIM 1.5.2 compatibility
  # - changed parameter iniPassword (maxlength and format)
  # - changed parameter referenceId (maxlength) for KIM 1.5.2 compatibility
  # - added enum for regStat in schemas /Account for KIM 1.5.2 compatibility
  # - added in schemas /Account dataTimeToLive for KIM 1.5.2 compatibility
  # - added in schemas /Account maxMailSize (changed minimum and added maximum value) for KIM 1.5.2 compatability
### 2.3.1
  # KIM 1.5.3 changes
  # - values for regStat defined (registered and deregistered)
  # - parameter password in createCert is optional (description changed)
  # - descriptions changed
  # - read only parameter in setAccount removed
  # - new parameter appTags in registerAccount and setAccount
  # - added traceId to Error object
  # - changed servers -url
  # - added "noVzdMailEntry" flag for POST /account and PUT /account/{username}
  # - changed type for password format to byte
  # - new error code for VZD entry is locked
  ### 2.3.0
  # - change server url to new api version
  # - added /account/{username}/revokeDeregistration
  #   to allow customers to revoke the deregistration process
  # - changed description for externalDoc to Github
  # - added status Code 502 for operation createCert in case the account manager acts as a proxy
  # - added status Code 403 for operation setTID in case the token is not valid
  # - added format int64 for deregDate property
  # - changed otp property to lowercase and added password as format
  # - added response code 404 for getOTP in case e-mail account does not exist
  # - added response code 404 for deregisterAccount in case e-mail account does not exist
  ### 2.2.0
  # - updated url to https://account-manager.hrst1.kim.telematik/AccountMgmt/v2.2
  # - changed /components/schemas/Account:
  #   added parameter dataTimeToLive & maxMailSize
  #   specified kimVersion with enum
  # - changed operation createCert:
  #   added error codes 400 & 404
  ### 2.0.0
  # - included new operations for outOfOffice
  # - included new operations for porting an e-mail address to new telematikID
  # - removed operations: register_State, cm_version and pw_change
  # - added new operations setAccount and getAccount
  # - renamed and updated operations for user account (e.g. registerAccount and
  #   deregisterAccount)
  # - added operation createCert to generate PKCS#12 files
  # - added HTTP error code 500
  # - changed authentication to JWT
  ### 1.2.0
  # - added parameter "cert" to all operations. It includes the auth certificate to sign the operation. This is necessary to check the sign from the Server.
  # - adjusted some tags
  # - more specified parameter "username" (email & maxlength)
  # - changed response code of the operation "register" from 200 - OK to 201 - created
  # - changed http method in operation "deregister" from PUT to DELETE
  # - changed http method in operation "cm_version" from GET to PUT
  # - changed response in operation "register_state" to JSON format
  ### 1.1.2
  # - added parameter "referenceID" in operation "register"
  ### 1.1.1
  # - extended URI to interface releases
  ### 1.1.0
  # - added authentication with HBA/SMC-B
  ### 1.0.0
  # - initial Version of I_AccountManager_Service

externalDocs:
  description: GitHub documentation
  url: https://github.com/gematik/api-kim

servers:
- url: /AccountMgmt/v2.4/
  # The URL must be formed as described in requirement [A_19524-*], see https://gemspec.gematik.de/docs/gemSpec/gemSpec_FD_KOMLE/latest
tags:
- name: Email-Account
- name: Certificate
- name: Out of Office Notification
- name: Porting

security:
  - KIMBearerAuth: []
    # Authentication is carried out for all operations via a JWT

paths:
  /account:
    post:
      tags:
      - Email-Account
      summary: Register a new email account.
            #  In all error cases, the account is not created.
      operationId: registerAccount
      parameters:
      - in: header
        name: iniPassword
        description: Optional initial password for the email account. When provided, the value must be base64 encoded.
        # To see if the service requires an initial password, check ServiceInformation.initialPasswordRequired.
        required: false
        schema:
          $ref: 'CommonSchemas.yaml#/components/schemas/Password'
      requestBody:
        description: Register a new account.
        content:
          application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Account'
        required: true
      responses:
        204:
          description: Account registered successfully.
        400:
          $ref: 'CommonSchemas.yaml#/components/responses/400'
        401:
          $ref: 'CommonSchemas.yaml#/components/responses/401'
          # Authentication via referenceID/iniPassword and signature of the operation failed.
          # This error also occurs if the referenceID does not match the signature's AUT certificate (cert) or was not specified.
        403:
          description: Initial password must be changed before this operation is allowed; it was not changed as required (see A_21385-*).
          content:
            application/json; charset=utf-8:
              schema:
                $ref: 'CommonSchemas.yaml#/components/schemas/Error'       
        409:
          description: An account with the same email address already exists.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: 'CommonSchemas.yaml#/components/schemas/Error'
        422:
          $ref: 'CommonSchemas.yaml#/components/responses/422'
        423:
          $ref: 'CommonSchemas.yaml#/components/responses/423'
        500:
          $ref: 'CommonSchemas.yaml#/components/responses/500'
        502:
          $ref: 'CommonSchemas.yaml#/components/responses/502'

  /account/{username}:
    put:
      tags:
      - Email-Account
      summary: Change account values.
              Unspecified writable properties remain unchanged.
              # referenceID & username (in the body) cannot be changed via this operation
      operationId: setAccount
      parameters:
      - $ref: '#/components/parameters/AccountUsername'
      - $ref: '#/components/parameters/AccountPassword'
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/Account'
      responses:
        204:
          description: Account change successful.
        400:
          $ref: 'CommonSchemas.yaml#/components/responses/400'
        401:
          $ref: 'CommonSchemas.yaml#/components/responses/401'
        404:
          $ref: 'CommonSchemas.yaml#/components/responses/404'
        422:
          $ref: 'CommonSchemas.yaml#/components/responses/422'
        423:
          $ref: 'CommonSchemas.yaml#/components/responses/423'
        500:
          $ref: 'CommonSchemas.yaml#/components/responses/500'
        502:
          $ref: 'CommonSchemas.yaml#/components/responses/502'

    delete:
      tags:
      - Email-Account
      summary: Deregisters a mail account.
      operationId: deregisterAccount
      parameters:
      - $ref: '#/components/parameters/AccountUsername'
      - $ref: '#/components/parameters/AccountPassword'
      responses:
        204:
          description: Account deregistered successfully.
        400:
          $ref: 'CommonSchemas.yaml#/components/responses/400'
        401:
          $ref: 'CommonSchemas.yaml#/components/responses/401'
        404:
          $ref: 'CommonSchemas.yaml#/components/responses/404'
        500:
          $ref: 'CommonSchemas.yaml#/components/responses/500'
        502:
          $ref: 'CommonSchemas.yaml#/components/responses/502'

    get:
      tags:
      - Email-Account
      summary: Display the account details.
      operationId: getAccount
      parameters:
      - $ref: '#/components/parameters/AccountUsername'
      - $ref: '#/components/parameters/AccountPassword'
      responses:
        200:
          description: Display the account.
          content:
            application/json; charset=utf-8:
             schema:
               $ref: '#/components/schemas/Account'
        400:
          $ref: 'CommonSchemas.yaml#/components/responses/400'
        401:
          $ref: 'CommonSchemas.yaml#/components/responses/401'
        404:
          $ref: 'CommonSchemas.yaml#/components/responses/404'
        500:
          $ref: 'CommonSchemas.yaml#/components/responses/500'
        502:
          $ref: 'CommonSchemas.yaml#/components/responses/502'

  /account/{username}/revokeDeregistration:
    put:
      tags:
      - Email-Account
      summary: Revoke account deregistration.
      operationId: revokeDeregistration
      parameters:
      - $ref: '#/components/parameters/AccountUsername'
      - $ref: '#/components/parameters/AccountPassword'
      responses:
        204:
          description: Deregistration revoked successfully.
        400:
          $ref: 'CommonSchemas.yaml#/components/responses/400'
        401:
          $ref: 'CommonSchemas.yaml#/components/responses/401'
        403:
          description: The email account has not been deregistered yet.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: 'CommonSchemas.yaml#/components/schemas/Error'
        404:
          $ref: 'CommonSchemas.yaml#/components/responses/404'
        423:
          $ref: 'CommonSchemas.yaml#/components/responses/423'
        500:
          $ref: 'CommonSchemas.yaml#/components/responses/500'
        502:
          $ref: 'CommonSchemas.yaml#/components/responses/502'

  /account/{username}/OTP:
    get:
      tags:
      - Porting
      summary: Generate a one-time password (OTP) for porting the email address to a new telematikID.
      operationId: getOTP
      description: This operation creates a One Time Password (OTP) for the KIM account/email address,
                   with which the email address can be ported to a telematikID (card).
                   Authentication takes place with the previous card.
      parameters:
      - $ref: '#/components/parameters/AccountUsername'
      - $ref: '#/components/parameters/AccountPassword'
      responses:
        200:
          description: OTP generated successfully.
          content:
           application/json; charset=utf-8:
            schema:
              type: object
              properties:
                otp:
                  type: string
                  maxLength: 256
                  format: byte
                  # Value must be base64 encoded.
                  description: One-time password for porting the KIM email address to another telematikID.
                               The password must be transmitted as a base64-encoded value.
        400:
          $ref: 'CommonSchemas.yaml#/components/responses/400'
        401:
          $ref: 'CommonSchemas.yaml#/components/responses/401'
        404:
          $ref: 'CommonSchemas.yaml#/components/responses/404'
        500:
          $ref: 'CommonSchemas.yaml#/components/responses/500'

  /account/{username}/telematikID:
    put:
      tags:
      - Porting
      summary: Port the email address to a new telematikID.
      operationId: setTID
      description: This operation removes the email address from the previous VZD entry and writes it
           to the new VZD entry that corresponds to the authentication data used for setTID.
           Authentication is performed with the new card/identitity.
      parameters:
      - $ref: '#/components/parameters/AccountUsername'
      - $ref: '#/components/parameters/AccountPassword'
      - in: header
        name: otp
        description: One-time password (OTP) returned by getOTP.
        required: true
        schema:
          $ref: 'CommonSchemas.yaml#/components/schemas/Password'
      responses:
        204:
          description: TelematikID changed successfully.
        400:
          $ref: 'CommonSchemas.yaml#/components/responses/400'
        401:
          $ref: 'CommonSchemas.yaml#/components/responses/401'
        403:
          description: Invalid OTP
          content:
            application/json; charset=utf-8:
              schema:
                $ref: 'CommonSchemas.yaml#/components/schemas/Error'
        404:
          $ref: 'CommonSchemas.yaml#/components/responses/404'
        408:
          description: Request Timeout
          content:
            application/json; charset=utf-8:
              schema:
                $ref: 'CommonSchemas.yaml#/components/schemas/Error'
        423:
          $ref: 'CommonSchemas.yaml#/components/responses/423'
        500:
          $ref: 'CommonSchemas.yaml#/components/responses/500'
        502:
          $ref: 'CommonSchemas.yaml#/components/responses/502'

  /account/{username}/cert:
    post:
      tags:
      - Certificate
      summary: Create a TLS AUT certificate.
      operationId: createCert
      parameters:
      - $ref: '#/components/parameters/AccountUsername'
      - $ref: '#/components/parameters/AccountPassword'
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
             $ref: '#/components/schemas/CertificateParameters'

      responses:
        200:
          description: Returns the certificate.
          content:
           application/json; charset=utf-8:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Base64-encoded PKCS#12 container. If certPassword is provided in the request,
                               the container is protected with that password.
        400:
          $ref: 'CommonSchemas.yaml#/components/responses/400'
          # e.g. no CommonName or CertPassword specified
        401:
          $ref: 'CommonSchemas.yaml#/components/responses/401'
        404:
          $ref: 'CommonSchemas.yaml#/components/responses/404'
        500:
          $ref: 'CommonSchemas.yaml#/components/responses/500'
        502:
          $ref: 'CommonSchemas.yaml#/components/responses/502'
          # CMP service cannot be reached or returns errors

  /account/{username}/outofoffice:
    get:
      tags:
      - Out of Office Notification
      summary: Read the Out of Office Notification
      operationId: getOutOfOffice
      parameters:
      - $ref: '#/components/parameters/AccountUsername'
      - $ref: '#/components/parameters/AccountPassword'
      responses:
        200:
          description: Out-of-office message returned successfully.
          content:
           application/json; charset=utf-8:
            schema:
             $ref: '#/components/schemas/OutOfOfficeNotification'
        400:
          $ref: 'CommonSchemas.yaml#/components/responses/400'
        401:
          $ref: 'CommonSchemas.yaml#/components/responses/401'
        404:
          $ref: 'CommonSchemas.yaml#/components/responses/404'
        500:
          $ref: 'CommonSchemas.yaml#/components/responses/500'

    put:
      tags:
      - Out of Office Notification
      summary: Update the Out of Office Notification
      operationId: updateOutOfOffice
      parameters:
      - $ref: '#/components/parameters/AccountUsername'
      - $ref: '#/components/parameters/AccountPassword'
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
             $ref: '#/components/schemas/OutOfOfficeNotification'
      responses:
        204:
          description: Out-of-office notification updated successfully.
        400:
          $ref: 'CommonSchemas.yaml#/components/responses/400'
        401:
          $ref: 'CommonSchemas.yaml#/components/responses/401'
        404:
          $ref: 'CommonSchemas.yaml#/components/responses/404'
        500:
          $ref: 'CommonSchemas.yaml#/components/responses/500'

components:
  parameters:
    AccountUsername:
      name: username
      in: path
      description: Username or email address of the account.
      required: true
      schema:
        $ref: 'CommonSchemas.yaml#/components/schemas/Username'

    AccountPassword:
      in: header
      name: password
      description: Password for the email account. The value must be base64 encoded.
      required: true
      schema:
        $ref: 'CommonSchemas.yaml#/components/schemas/Password'

  schemas:
    Account:
      type: object
      properties:
        referenceID:
          type: string
          maxLength: 256
          description: The KIM provider determines the referenceID and communicates it to the KIM participant.
                       For example, it can contain a contract number or a registration code.
                       The KIM provider must inform its KIM participants about the use of this parameter.
                       All administration modules (or client modules) must use this parameter - because of the
                       Interoperability support required by all KIM specialist services. This value cannot be changed
                       through the "setAccount" operation.
        username:
          $ref: 'CommonSchemas.yaml#/components/schemas/Username'

        password:
          $ref: 'CommonSchemas.yaml#/components/schemas/Password'

        kimVersion:
          type: string
          maxLength: 4
          example: 1.5+
          description: The KIM participant can change his KIM version. The range of values supported
                       KIM versions should be specified by the client module.

        regStat:
          type: string
          enum:
            - registered
            - deregistered
          example: registered
          description: The registration status of the account. Valid values are registered and deregistered.

        deregDate:
          type: integer
          format: int64
          example: 1616588543
          description: Confirmed termination date (Unix timestamp).
                       Until deregDate POP3 is usable.

        dataTimeToLive:
          type: integer
          minimum: 10
          maximum: 365
          default: 90
          example: 90
          description: Storage period for emails and attachments on the KAS service.
                       Specified in days.

        maxMailSize:
          type: integer
          format: int64
          minimum: 734003200
          maximum: 734003200
          example: 734003200
          readOnly: true
          description: The maximum size of a KIM email in bytes.

        noVzdMailEntry:
          type: boolean
          description: If "noVzdMailEntry == true", the VZD does not populate the data in "mail" and
                       "komLeData" attributes. In the case of PUT, existing "mail" and "komLeData" attributes are deleted by the VZD.
                       This attribute should only be supported on the client side by the Basis Consumer.

    CertificateParameters:
      type: object
      properties:
        commonName:
          type: string
          writeOnly: true
          description: Included in the certificate attribute cn as <commonName> + "#CM".
                       The certificate is used as a TLS client certificate when connecting to the KIM services.
        certPassword:
           # base64 encoded password for the PKCS#12 container in which the certificate is transported.
           # If no certPassword is specified, then the PKCS#12 container will not be encrypted.
          $ref: 'CommonSchemas.yaml#/components/schemas/Password'

    OutOfOfficeNotification:
      type: object
      properties:
        startDate:
          type: string
          format: date-time
          example: 2021-07-20T17:32:28Z
          description: From this point on, the absence notice will be sent.
        endDate:
          type: string
          format: date-time
          example: 2021-07-28T17:32:28Z
          description: After this point, the out-of-office notice will no longer be sent.
        message:
          type: string
          maxLength: 2048
          description: Contents of the out-of-office note.
        active:
          type: boolean
          description: Enables or disables the out-of-office notification.

  securitySchemes:
    KIMBearerAuth:
      $ref: 'CommonSchemas.yaml#/components/securitySchemes/KIMBearerAuth'