openapi: 3.0.3
info:
  title: Mobile ID REST API
  description: |
    Mobile ID API for requesting mobile signatures.
  version: 1.0.1
servers:
  - url: 'https://mobileid.swisscom.com'
tags:
  - name: ETSI TS 102 204 REST API
    description: ETSI TS 102 204 based REST API for requesting Mobile Signature Service
paths:
  /rest/service/sign:
    post:
      tags:
        - ETSI TS 102 204
      summary: Send a Mobile Signature Service request
      requestBody:
        description: Mobile Signature Service request
        content:
          application/json:
            schema:
              title: SignatureReq
              type: object
              properties:
                MSS_SignatureReq:
                  type: object
                  properties:
                    AP_Info:
                      $ref: '#/components/schemas/AP_Info'
                    MSSP_Info:
                      $ref: '#/components/schemas/MSSP_Info'
                    MajorVersion:
                      type: string
                      enum:
                        - '1'
                      example: '1'
                    MinorVersion:
                      type: string
                      enum:
                        - '2'
                      example: '2'
                    MobileUser:
                      $ref: '#/components/schemas/MobileUser'
                    MessagingMode:
                      type: string
                      enum:
                        - asynch
                        - synch
                    SignatureProfile:
                      $ref: '#/components/schemas/SignatureProfile'
                    TimeOut:
                      type: string
                    DataToBeSigned:
                      $ref: '#/components/schemas/DataToBeSigned'
                    AdditionalServices:
                      type: array
                      items:
                        $ref: '#/components/schemas/AdditionalService'
                  required:
                    - AP_Info
                    - MSSP_Info
                    - MobileUser
                    - MessagingMode
                    - MajorVersion
                    - MinorVersion
                    - DataToBeSigned
                    - AdditionalServices
                    - SignatureProfile
                    - TimeOut
              required:
                - MSS_SignatureReq
        required: true
      responses:
        '200':
          description: >-
            A Mobile Signature response has been received. Check the StatusCode
            for details. In asynchorous mode this will never contain a
            signature, and contains an MSSP_TransId instead.
          content:
            application/json:
              schema:
                title: SignatureResp
                type: object
                properties:
                  MSS_SignatureResp:
                    type: object
                    properties:
                      AP_Info:
                        $ref: '#/components/schemas/AP_Info'
                      MSSP_Info:
                        $ref: '#/components/schemas/MSSP_Info'
                      MajorVersion:
                        type: string
                        enum:
                          - '1'
                        example: '1'
                      MinorVersion:
                        type: string
                        enum:
                          - '1'
                        example: '1'
                      MobileUser:
                        $ref: '#/components/schemas/MobileUser'
                      MSSP_TransID:
                        type: string
                        example: h44okl
                      MSS_Signature:
                        $ref: '#/components/schemas/MSS_Signature'
                      Status:
                        $ref: '#/components/schemas/SignatureStatus'
                      SignatureProfile:
                        $ref: '#/components/schemas/SignatureProfile'
                      ServiceResponses:
                        type: array
                        items:
                          $ref: '#/components/schemas/ServiceResponse'
        '500':
          description: Mobile Signature request failed. See fault error code for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fault'
  /rest/service/status:
    post:
      tags:
        - ETSI TS 102 204
      summary: >-
        Request the Mobile Signature Service status of an asynchronous signature
        request.
      requestBody:
        description: Status request
        content:
          application/json:
            schema:
              title: StatusReq
              type: object
              properties:
                MSS_StatusReq:
                  type: object
                  properties:
                    AP_Info:
                      $ref: '#/components/schemas/AP_Info'
                    MSSP_Info:
                      $ref: '#/components/schemas/MSSP_Info'
                    MajorVersion:
                      type: string
                      enum:
                        - '1'
                    MinorVersion:
                      type: string
                      enum:
                        - '1'
                    MSSP_TransID:
                      type: string
                      example: h4iof
                  required:
                    - AP_Info
                    - MSSP_Info
                    - MajorVersion
                    - MinorVersion
                    - MSSP_TransID
              required:
                - MSS_StatusReq
        required: true
      responses:
        '200':
          description: >-
            Mobile Signature Service response has been received. Check the
            StatusCode for details.
          content:
            application/json:
              schema:
                title: StatusResp
                type: object
                properties:
                  MSS_StatusResp:
                    properties:
                      AP_Info:
                        $ref: '#/components/schemas/AP_Info'
                      MSSP_Info:
                        $ref: '#/components/schemas/MSSP_Info'
                      MajorVersion:
                        type: string
                        enum:
                          - '1'
                      MinorVersion:
                        type: string
                        enum:
                          - '1'
                      MobileUser:
                        $ref: '#/components/schemas/MobileUser'
                      MSS_Signature:
                        $ref: '#/components/schemas/MSS_Signature'
                      Status:
                        $ref: '#/components/schemas/SignatureStatus'
                      ServiceResponses:
                        type: array
                        items:
                          $ref: '#/components/schemas/ServiceResponse'
        '500':
          description: >-
            Mobile Signature Service status query failed. See fault error code
            for details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fault'
  /rest/service/receipt:
    post:
      tags:
        - ETSI TS 102 204
      summary: >-
        Send the Mobile Signature Receipt. You can send the Receipt after a
        successful Mobile Signature.
      requestBody:
        description: Mobile Signature Service Receipt request
        content:
          application/json:
            schema:
              title: ReceiptReq
              type: object
              properties:
                MSS_ReceiptReq:
                  type: object
                  properties:
                    AP_Info:
                      $ref: '#/components/schemas/AP_Info'
                    MSSP_Info:
                      $ref: '#/components/schemas/MSSP_Info'
                    MajorVersion:
                      type: string
                      enum:
                        - '1'
                    MinorVersion:
                      type: string
                      enum:
                        - '1'
                    MSSP_TransID:
                      $ref: '#/components/schemas/MSSP_TransID'
                    Message:
                      $ref: '#/components/schemas/ReceiptMessage'
                    MobileUser:
                      $ref: '#/components/schemas/MobileUser'
                    Status:
                      $ref: '#/components/schemas/ReceiptReqStatus'
                  required:
                    - AP_Info
                    - MSSP_Info
                    - MajorVersion
                    - MinorVersion
                    - MSSP_TransID
                    - Status
                    - MobileUser
                    - Message
              required:
                - MSS_ReceiptReq
        required: true
      responses:
        '200':
          description: >-
            Mobile Signature Service Receipt request has been send. Check the
            Status for details.
          content:
            application/json:
              schema:
                title: ReceiptResp
                type: object
                properties:
                  MSS_ReceiptResp:
                    type: object
                    properties:
                      AP_Info:
                        $ref: '#/components/schemas/AP_Info'
                      MSSP_Info:
                        $ref: '#/components/schemas/MSSP_Info'
                      MajorVersion:
                        type: string
                        enum:
                          - '1'
                      MinorVersion:
                        type: string
                        enum:
                          - '1'
                      Status:
                        $ref: '#/components/schemas/ReceiptRespStatus'
        '500':
          description: >-
            Mobile Signature Service Receipt sending failed. See fault error
            code for details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fault'
  /rest/service/profile:
    post:
      tags:
        - ETSI TS 102 204
      summary: Query Mobile Signature Service Profile of an user.
      requestBody:
        description: Send a Profile request
        content:
          application/json:
            schema:
              title: ProfileReq
              type: object
              properties:
                MSS_ProfileReq:
                  type: object
                  properties:
                    AP_Info:
                      $ref: '#/components/schemas/AP_Info'
                    MSSP_Info:
                      $ref: '#/components/schemas/MSSP_Info'
                    MajorVersion:
                      type: string
                      enum:
                        - '2'
                    MinorVersion:
                      type: string
                      enum:
                        - '0'
                    Params:
                      type: string
                      example: sscds state certs pinstatus rcstatus aastatus
                    MobileUser:
                      $ref: '#/components/schemas/MobileUser'
                  required:
                    - AP_Info
                    - MSSP_Info
                    - MajorVersion
                    - MinorVersion
                    - Params
                    - MobileUser
              required:
                - MSS_ProfileReq
        required: true
      responses:
        '200':
          description: >-
            Profile Query succeeded and user is eligible for Mobile Signature
            Service. See the Status element for profile details of the user.
          content:
            application/json:
              schema:
                title: ProfileResp
                type: object
                properties:
                  MSS_ProfileResp:
                    type: object
                    properties:
                      AP_Info:
                        $ref: '#/components/schemas/AP_Info'
                      MSSP_Info:
                        $ref: '#/components/schemas/MSSP_Info'
                      MajorVersion:
                        type: string
                        enum:
                          - '2'
                      MinorVersion:
                        type: string
                        enum:
                          - '0'
                      SignatureProfile:
                        type: array
                        items:
                          $ref: '#/components/schemas/SignatureProfile'
                      Status:
                        $ref: '#/components/schemas/ProfileStatus'
        '500':
          description: Profile Query failed. See fault error code for details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fault'
components:
  schemas:
    Fault:
      type: object
      properties:
        Fault:
          type: object
          properties:
            Code:
              type: object
              properties:
                Value:
                  type: string
                  example: Receiver
                ValueNs:
                  type: string
                  example: 'http://www.w3.org/2003/05/soap-envelope'
                SubCode:
                  type: object
                  properties:
                    Value:
                      type: string
                      example: _401
                    ValueNs:
                      type: string
                      example: 'http://uri.etsi.org/TS102204/v1.1.2#'
            Detail:
              type: string
              example: User cancelled the request
            Reason:
              type: string
              example: USER_CANCEL
    MSSP_TransID:
      type: string
      example: h4iof
    ReceiptMessage:
      type: object
      properties:
        MimeType:
          type: string
          description: MIME type of the data.
          example: text/plain
        Encoding:
          type: string
          description: Data encoding
          example: UTF-8
        Data:
          type: string
          example: Receipt message
      required:
        - MimeType
        - Encoding
        - Data
    MSS_Signature:
      type: object
      properties:
        Base64Signature:
          type: string
          description: Signature in Base64 format
          example: MIIIdwYJKoZIhvc...
          format: byte
    DataToBeSigned:
      type: object
      description: Data that the user signs
      properties:
        MimeType:
          type: string
          description: MIME type of the data.
          example: text/plain
        Encoding:
          type: string
          description: Data encoding
          example: UTF-8
        Data:
          type: string
          example: Please sign this
      required:
        - MimeType
        - Encoding
        - Data
    MobileUser:
      type: object
      description: Mobile user.
      properties:
        MSISDN:
          type: string
          description: User MSISDN
          example: +2280112xxx
      required:
        - MSISDN
    MSSP_Info:
      type: object
      properties:
        MSSP_ID:
          $ref: '#/components/schemas/MSSP_ID'
        Instant:
          type: string
          example: '2021-04-07T11:00:00.100Z'
          description: MSSP timestamp. This is not required in request messages
          format: date-time
      required:
        - MSSP_ID
        - Instant
    MSSP_ID:
      type: object
      properties:
        URI:
          type: string
          example: 'http://mid.swisscom.ch/'
      required:
        - URI
    AP_Info:
      type: object
      properties:
        AP_ID:
          type: string
          example: your AP_ID
        AP_PWD:
          type: string
          example: your AP_PWD
        AP_TransID:
          type: string
          example: REF0101120000
        Instant:
          type: string
          example: '2021-04-01T11:00:00.000Z'
          format: date-time
      required:
        - AP_ID
        - AP_TransID
        - Instant
    AdditionalService:
      type: object
      description: Additional Service in the Mobile Signature request.
      properties:
        Description:
          type: string
          enum:
            - 'http://mss.ficom.fi/TS102204/v1.0.0#userLang'
            - 'http://mid.swisscom.ch/as#geofencing'
            - 'http://mid.swisscom.ch/as#app2app'
            - 'http://mid.swisscom.ch/as#subscriberInfo'
        UserLang:
          type: object
          nullable: true
          properties:
            Value:
              type: string
              example: DE
        App2App:
          type: object
          nullable: true
          properties:
            RedirectUri:
              type: string
              example: 'myapp://example'
      required:
        - Description
      example:
        Description: 'http://mss.ficom.fi/TS102204/v1.0.0#userLang'
        UserLang:
          Value: DE
    ServiceResponse:
      type: object
      description: >-
        Response to a requested Additional Service. One ServiceResponse element
        contains response of only one AdditionalService. Check the description
        to resolve which response type it contains.
      properties:
        Description:
          type: string
          enum:
            - 'http://mid.swisscom.ch/as#geofencing'
            - 'http://mid.swisscom.ch/as#app2app'
            - 'http://mid.swisscom.ch/as#subscriberInfo'
        Geofencing:
          type: object
          nullable: true
          description: >-
            Response to geofencing AdditionalService. Can be an error, or
            succesful response. Is an error if ErrorCode is present.
          properties:
            Country:
              type: string
              example: CH
            Accuracy:
              type: string
              example: '16'
            DeviceConfidence:
              type: string
              example: '1.0'
            LocationConfidence:
              type: string
              example: '1.0'
            Timestamp:
              type: string
              example: '2021-01-01T11:00:00.000+01:00'
              format: date-time
            ErrorCode:
              type: string
              example: '100'
            ErrorMessage:
              type: string
              example: Geofencing feature disabled
        App2App:
          description: Response to App2App AdditionalService.
          type: object
          nullable: true
          properties:
            AuthUri:
              type: string
              example: >-
                mobileid://auth?mobile_auth_redirect_uri=myapp%3A%2F%2Fapp.open%23access_token%3DABCD&session_token=32ffc297-0N5F0yEk2ArMZjFhBWPb4Uifwbk1f3p9ciAURd_QhUQ9e&user_id=32ffc297-ac33-4be2-b3f4-42588502ea0f
        SubscriberInfo:
          description: Response to SubscriberInfo AdditionalService
          type: object
          nullable: true
          properties:
            Details:
              type: array
              items:
                $ref: '#/components/schemas/Details'
      example:
        Description: 'http://mid.swisscom.ch/as#app2app'
        App2App:
          AuthUri: >-
            mobileid://auth?mobile_auth_redirect_uri=myapp%3A%2F%2Fapp.open%23access_token%3DABCD&session_token=32ffc297-0N5F0yEk2ArMZjFhBWPb4Uifwbk1f3p9ciAURd_QhUQ9e&user_id=32ffc297-ac33-4be2-b3f4-42588502ea0f
    SignatureStatus:
      type: object
      properties:
        StatusMessage:
          type: string
          example: SIGNATURE
        StatusCode:
          $ref: '#/components/schemas/StatusCode'
    StatusCode:
      type: object
      properties:
        Value:
          type: string
          example: '500'
    ReceiptReqStatus:
      type: object
      properties:
        StatusCode:
          type: object
          properties:
            Value:
              type: string
              example: '100'
              enum:
                - '100'
        StatusDetail:
          type: object
          properties:
            ReceiptRequestExtension:
              type: object
              properties:
                ReceiptMessagingMode:
                  type: string
                  enum:
                    - synch
                ReceiptProfile:
                  type: object
                  properties:
                    Language:
                      type: string
                      example: DE
                    ReceiptProfileURI:
                      type: string
                      example: 'http://mss.swisscom.ch/synch'
                UserAck:
                  type: string
                  enum:
                    - 'true'
                    - 'false'
              required:
                - ReceiptMessagingMode
                - ReceiptProfile
                - UserAck
      required:
        - StatusCode
        - StatusDetail
    ReceiptRespStatus:
      type: object
      properties:
        StatusCode:
          type: object
          properties:
            Value:
              type: string
              example: '100'
        StatusDetail:
          type: object
          properties:
            ReceiptResponseExtension:
              type: object
              properties:
                ReceiptMessagingMode:
                  type: string
                  enum:
                    - synch
                UserAck:
                  type: string
                  enum:
                    - 'true'
                    - 'false'
                ClientAck:
                  type: string
                  enum:
                    - 'true'
                    - 'false'
                NetworkAck:
                  type: string
                  enum:
                    - 'true'
                    - 'false'
                UserResponse:
                  type: string
                  example: '{"status":"OK"}'
    SignatureProfile:
      type: string
      example: 'http://mid.swisscom.ch/STK-LoA4'
      enum:
        - 'http://mid.swisscom.ch/Any-LoA4'
        - 'http://mid.swisscom.ch/MID/v1/AuthProfile1'
        - 'http://mid.swisscom.ch/STK-LoA4'
        - 'http://mid.swisscom.ch/Device-LoA4'
        - 'http://mid.swisscom.ch/MID/v1/AuthProfile1.ECC'
        - 'http://mid.swisscom.ch/MID/v1/AuthProfile1.RSA'
        - 'http://mid.swisscom.ch/Any-Geofencing-LoA4'
        - 'http://mid.swisscom.ch/MID/v1/OtpProfileFlash'
        - 'http://mid.swisscom.ch/MID/v1/OtpProfileText'
    Details:
      description: SubscriberInfo AdditionalService Details. ID 1901 is MCCMNC.
      type: object
      properties:
        id:
          type: string
          example: '1901'
        value:
          type: string
          example: '26200'
    ProfileStatus:
      type: object
      properties:
        StatusCode:
          type: object
          properties:
            Value:
              type: string
              example: '100'
        StatusDetail:
          type: object
          properties:
            ProfileQueryExtension:
              $ref: '#/components/schemas/ProfileQueryExtension'
        StatusMessage:
          type: string
          example: REQUEST_OK
    ProfileQueryExtension:
      type: object
      properties:
        MobileUser:
          type: object
          properties:
            AutoActivation:
              type: boolean
            RecoveryCodeCreated:
              type: boolean
        Sscds:
          type: object
          properties:
            App:
              type: array
              items:
                $ref: '#/components/schemas/Sscd'
            Sim:
              $ref: '#/components/schemas/Sscd'
    Sscd:
      type: object
      properties:
        MobileUserCertificate:
          type: array
          items:
            $ref: '#/components/schemas/MobileUserCertificate'
        PinStatus:
          type: object
          properties:
            Blocked:
              type: boolean
        State:
          type: string
          example: ACTIVE
          enum:
            - ACTIVE
            - INACTIVE
            - REGISTERED
        CardDetails:
          description: 'Contains user SIM details (MCC, MNC, and network)'
          type: object
          properties:
            Mcc:
              description: 'SIM MCC. If unknown, value is 000.'
              type: string
              example: '228'
            Mnc:
              description: 'SIM MNC. If unknown, value is 00.'
              type: string
              example: '01'
            Network:
              description: 'SIM network name. If unknonw, value is ''Unknown network''.'
              type: string
              example: Swisscom
    MobileUserCertificate:
      type: object
      properties:
        Algorithm:
          type: string
          example: RSA
        State:
          type: string
          example: ACTIVE
          enum:
            - ACTIVE
            - INACTIVE
          description: State of the certificate.
        X509Certificate:
          type: array
          items:
            type: string
            example: X509_BASE64_CERT_USER
            format: byte
        X509SubjectName:
          type: array
          items:
            type: string
            example: X509_BASE64_SUBJECT_USER
            format: byte