mobileid.yaml

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: 'yourAP_ID'
        AP_PWD:
          type: string
          example: 'yourAP_PWD'
        AP_TransID:
          type: string
          example: 'REF0101120000'
        Instant:
          type: string
          example: '2021-04-01T11:00:00.000Z'
          format: date-time
      required:
        - AP_ID
        - AP_PWD
        - 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']
          
          
    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