swagger: '2.0'
info:
  version: '0.1'
  title: OMI API
  description: |
    When your platform makes a request to our API, it does so on behalf of one of your users. To do this securely, you must first obtain an access token for the user and then include that token in every subsequent request by setting the Authorization-header of the HTTP request. Requesting an access token requires the user's ID and password. You don't want to get a new token for every request; instead, you should re-use the token for multiple requests.

    However, the access token expires. If this happens, you should refresh it. When you request an access token, you will also get a refresh token. You can exchange this refresh token for a fresh access token (and a new refresh token). This way, your user won't have to re-enter their credentials, even if the access token expires.

    When you request an access token, you need to indicate which scopes you want to include in the token. A scope defines which endpoints you can call using the access token. For example, if you want to be able to use the access token for sending push notifications, you'll need to request the scope credential:omi:push-notification:post. You can request multiple scopes for a single access token. In fact, you will need to if you intend to check if your push notification was confirmed by the user, because that requires credential:omi:push-notification:status:get.

    You should request one access token for your user with all the required scopes. There's no need to request separate access tokens for each scenario. For example, if you want to use both QR codes and push notifications, you can request a single access token with the scopes credential:omi:enrol:qr:post, credential:omi:enrol:status:get, credential:omi:push-notification:post, and credential:omi:push-notification:status:get. Of course, you shouldn't request scopes you're never going to use, so if you don't intend to use QR codes, don't request the scopes credential:omi:login:qr:post and credential:omi:login:status:get.
host: www.iwelcome.com
basePath: /
tags:
  - name: qr-codes
    description: Request a QR code that the user can scan to enrol or login.
  - name: push-notifications
    description: Send a push notification to a user's authentication device.
  - name: managing-devices
    description: Manage OMI users and their devices.
schemes:
  - https
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://example-domain-uri.com/auth/oauth2.0/v1/authorize'
    tokenUrl: 'https://example-domain-uri.com/auth/oauth2.0/v1/token'
    scopes:
      credential:omi:enrol:status:get: Allows you to get the status of an enrolment.
      credential:omi:enrol:status:admin:get: Allows you to get the status of an enrolment belonging to any user.
      credential:omi:enrol:qr:post: Allows you to generate a QR code for the current user to enrol an authentication device.
      credential:omi:enrol:qr:admin:post: Allows you to generate a QR code for any user to enrol an authentication device.
      credential:omi:push-notification:device:post: Allows you to push a notification to the current user's authentication device(s).
      credential:omi:push-notification:device:admin:post: Allows you to push a notification to any user's authentication device(s).
      credential:omi:push-notification:status:get: Allows you to get the status of a push notification.
      credential:omi:push-notification:status:admin:get: Allows you to get the status of a push notification belonging to any user.
      credential:omi:devices:get: Allows you to list the current user's devices.
      credential:omi:devices:admin:get: Allows you to list any user's devices.
      credential:omi:device:delete: Allows you to delete an device belonging to the authenticated user.
      credential:omi:device:admin:delete: Allows you to delete an device belonging to any user.
      credential:omi:user:devices:delete: Allows you to delete all devices belonging to the authenticated user.
      credential:omi:user:devices:admin:delete: Allows you to delete all devices belonging to any user.

paths:
  /omi/qr/enrol:
    post:
      security:
        - OAuth2: [ 'credential:omi:enrol:qr:post','credential:omi:enrol:qr:admin:post' ]
      tags:
        - qr-codes
      summary: Generate QR code for enrolment
      description: >-
        Get a QR code that you can display to the user. The user can then scan the QR code using the authenticator app on the device they wish to use for authentication in the future.
        This is a protected endpoint:
          - the user for this API needs to be authenticated using OAuth
          - regular users must have the 'credential:omi:enrol:qr:post' scope; admin users must have the 'credential:omi:enrol:qr:admin:post' scope
        For regular users, in case the request completes successfully, a success event is generated, named OMIEnrolmentQrCodeGenerationSuccessEvent. In case of failure, OMIEnrolmentQrCodeGenerationFailedEvent event is generated.
        For admin users, in case the request completes successfully, a success event is generated, named OMIAdminEnrolmentQrCodeGenerationSuccessEvent. In case of failure, OMIAdminEnrolmentQrCodeGenerationFailedEvent event is generated.
      operationId: generateQrCode
      parameters:
        - in: body
          name: qrEnrolRequest
          required: true
          schema:
            $ref: '#/definitions/QrEnrolRequest'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        201:
          description: Successfully generated a QR code
          schema:
            $ref: '#/definitions/QrEnrolResponse'
        400:
          description: 'Failed to create subscription, error code: CRE000101'
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: 'Full authentication is required.'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: CRE000003'
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: 'Internal server error, error code: CRE900001'
          schema:
            $ref: '#/definitions/ErrorResponse'

  /omi/qr/enrol/status:
    get:
      security:
        - OAuth2: [ 'credential:omi:enrol:status:get', 'credential:omi:enrol:status:admin:get' ]
      tags:
        - qr-codes
      operationId: getEnrolmentStatus
      summary: Check enrolment status
      description: >-
        This API can be used to verify if the user successfully scanned the QR code. It accepts the nonce attribute in the header, which was initially generated when creating the QR code.
        To call this API, an access token with the scope 'credential:omi:enrol:status:get' or 'credential:omi:enrol:status:admin:get' is needed.
        Once the API returns a 200 OK response, it means that the user successfully scanned the QR code. Using the same nonce again for this API will result in a 400 Bad Request, meaning the nonce is not valid anymore. However, the nonce can still be used for sending a push notification, and the notification will be sent to the device that was used to scan the QR code. Main reason of considering the nonce invalid once used, is to protect against enumeration attacks.
        In case the request completes successfully, a success event is generated, named EnrolOMIUserSuccessEvent. In case of failure, EnrolOMIUserFailedEvent event is generated. In case the Qr code expired, calling this API will result in an event generated, named OMIQRCodeEnrolmentTimeoutEvent.
      parameters:
        - name: X-iWelcome-Nonce
          description: The generated nonce when creating a QR code.
          required: true
          in: header
          type: string
          pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
          maxLength: 36
      produces:
        - application/json
      responses:
        200:
          description: >-
            The enrolment status response can have one of the following values: enrolled, pending, failed, or timeout.
            The userId and accountId will be returned when the status is enrolled.
          schema:
            $ref: '#/definitions/EnrolmentStatusResponse'
        400:
          description: Bad request, invalid nonce. Once the response returns that the user enrolled with success, using the same nonce on subsequent status requests will result in a 400 status code, with a message indicating that the nonce is invalid.
          schema:
            $ref: '#/definitions/ErrorResponse'
          examples:
            application/json:
              - error_code: CRE000065
                message: Operation failed.
                description: Invalid nonce provided.
              - error_code: CRE000067
                message: Missing request header.
                description: Request header nonce is missing.
        401:
          description: 'Full authentication is required.'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: CRE000003'
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: 'Internal server error, error code: CRE900001'
          schema:
            $ref: '#/definitions/ErrorResponse'

  /omi/push/user/{userId}/device/{deviceId}:
    post:
      security:
        - OAuth2: [ 'credential:omi:push-notification:device:post','credential:omi:push-notification:device:admin:post' ]
      tags:
        - push-notifications
      summary: Push a login notification to the user's app for a specific device
      description: >-
        Push a notification to a user's specific device.
        This is a protected endpoint:
                  - the user for this API needs to be authenticated using OAuth
                  - regular users must have 'credential:omi:push-notification:device:post' scope; admin users must have the
                    'credential:omi:push-notification:device:admin:post' scope
        For regular users, in case the request completes successfully, a success event is generated, named OMIPushDeviceNotificationSuccessEvent. In case of failure, OMIPushDeviceNotificationFailedEvent event is generated.
        For admin users, in case the request completes successfully, a success event is generated, named OMIAdminPushDeviceNotificationSuccessEvent. In case of failure, OMIAdminPushDeviceNotificationFailedEvent event is generated.
      operationId: pushNotificationToUserAndDevice
      parameters:
        - name: X-iWelcome-Nonce
          description: Nonce to identify the browser/webserver session.
          required: true
          in: header
          type: string
          pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
          maxLength: 36
        - name: userId
          in: path
          description: The id of the user
          required: true
          type: string
          pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
          maxLength: 36
        - name: deviceId
          in: path
          description: The id of the device
          required: true
          type: string
        - in: body
          name: notificationRequest
          description: Push user notification request
          required: true
          schema:
            $ref: '#/definitions/PushNotificationRequest'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        200:
          description: Success
          schema:
            $ref: '#/definitions/PushNotificationResponse'
        400:
          description: 'Failed to push user notification, error code: CRE000072'
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: 'Full authentication is required.'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: CRE000003'
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: 'Internal server error, error code: CRE900001'
          schema:
            $ref: '#/definitions/ErrorResponse'

  /omi/push/confirmation:
    get:
      security:
        - OAuth2: [ 'credential:omi:push-notification:status:get', 'credential:omi:push-notification:status:admin:get']
      tags:
        - push-notifications
      operationId: getNotificationStatus
      summary: Check if the user has confirmed.
      description: >-
        This API can be used to verify if the user successfully confirmed the notification. It accepts the nonce attribute in the header, which was initiated when the push notification was sent.
        This endpoint is protected with OAuth and regular users must have 'credential:omi:push-notification:status:get' scope and admin users must have 'credential:omi:push-notification:status:admin:get' scope.
        Once the API returns a 200 OK response, it means that the push notification has been confirmed, and using the same nonce again for subsequent calls to this API will result in a 400 bad request because the nonce will become invalid once used.
        Main reason of considering the nonce invalid once used, is to protect against enumeration attacks.
        In case the request completes successfully, a success event is generated, named OMIPushConfirmationSuccessEvent. In case the nonce expired, calling this API will result in an event generated, named OMIPushConfirmationTimeoutEvent.

      parameters:
        - name: X-iWelcome-Nonce
          description: The generated nonce when push notification was sent.
          required: true
          in: header
          type: string
          pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
          maxLength: 36
      produces:
        - application/json
      responses:
        200:
          description: >-
            The notification status response can have one of the following values: confirmed, pending, or timeout.
            The userId and accountId will be returned when the status is confirmed.
          schema:
            $ref: '#/definitions/NotificationStatusResponse'
        400:
          description: 'Failed to confirm notification, error code: CRE000071'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: CRE000003'
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: 'Internal server error, error code: CRE900001'
          schema:
            $ref: '#/definitions/ErrorResponse'
  /omi/users/{userId}/devices:
    get:
      security:
        - OAuth2: [ 'credential:omi:devices:get','credential:omi:devices:admin:get' ]
      tags:
        - managing-devices
      operationId: getUserDevices
      summary: Returns all user's devices
      description: >-
        This API returns all devices for a specific user, identified by the userId path parameter. In order to allow an
        authenticated user to get all his/her devices, the access token must have the scope 'credential:omi:devices:get'.
        This API can also be called by an administrator to return all the devices for a specific user, and in order to
        be able to do that, the scope 'credential:omi:devices:admin:get' is required. This API also generates two events, one success and one failed event.
        For regular users, in case the request completes successfully, a success event is generated, named OMIGetDevicesSuccessEvent. In case of failure, OMIGetDevicesFailedEvent event is generated.
        For admin users, in case the request completes successfully, a success event is generated, named OMIAdminGetDevicesSuccessEvent. In case of failure, OMIAdminGetDevicesFailedEvent event is generated.
      parameters:
        - name: userId
          description: The id of the user.
          required: true
          in: path
          type: string
          pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
          maxLength: 36
      produces:
        - application/json
      responses:
        200:
          description: Returns the user's devices
          schema:
            type: array
            items:
              $ref: '#/definitions/UserDeviceResponse'
        401:
          description: 'Full authentication is required.'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: CRE000003'
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: 'Internal server error, error code: CRE900001'
          schema:
            $ref: '#/definitions/ErrorResponse'
    delete:
      security:
        - OAuth2: [ 'credential:omi:user:devices:delete','credential:omi:user:devices:admin:delete' ]
      tags:
        - managing-devices
      operationId: deleteDevices
      summary: Delete all devices of a specific user
      description: >-
        This API deletes all devices of a specific user. The user itself is not deleted. In order to allow an
        authenticated user to delete all his/her devices, the access token must have the scope 'credential:omi:user:devices:delete'.
        This API can also be called by an administrator to delete a specific user's devices, and in order to be able
        to do that, the scope 'credential:omi:user:devices:admin:delete' is required.
        For regular users, in case the request completes successfully, a success event is generated, named OMIDeleteUserDevicesSuccessEvent. In case of failure, OMIDeleteUserDevicesFailedEvent event is generated.
        For admin users, in case the request completes successfully, a success event is generated, named OMIAdminDeleteUserDevicesSuccessEvent. In case of failure, OMIAdminDeleteUserDevicesFailedEvent event is generated.
      parameters:
        - name: userId
          description: The id of the user.
          required: true
          in: path
          type: string
          pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
          maxLength: 36
      responses:
        204:
          description: When all devices for this user have been revoked successfully
        400:
          description: 'Failed to delete user devices, error code: CRE000075'
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Full authentication is required.
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: CRE000003'
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: 'Internal server error, error code: CRE900001'
          schema:
            $ref: '#/definitions/ErrorResponse'

  /omi/users/{userId}/devices/{deviceId}:
    delete:
      security:
        - OAuth2: [ 'credential:omi:device:delete', 'credential:omi:device:admin:delete' ]
      tags:
        - managing-devices
      summary: Delete a specific device
      description: >-
        This API deletes a specific device.
        This is a protected endpoint:
                  - the user for this API needs to be authenticated using OAuth
                  - regular users must have the 'credential:omi:device:delete' scope; admin users must have the 'credential:omi:device:admin:delete' scope
        For regular users, in case the request completes successfully, a success event is generated, named OMIDeleteDeviceSuccessEvent. In case of failure, OMIDeleteDeviceFailedEvent event is generated.
        For admin users, in case the request completes successfully, a success event is generated, named OMIAdminDeleteDeviceSuccessEvent. In case of failure, OMIAdminDeleteDeviceFailedEvent event is generated.
      operationId: deleteDevice
      parameters:
        - name: userId
          in: path
          description: The id of the user
          required: true
          type: string
          pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
          maxLength: 36
        - name: deviceId
          in: path
          description: Identifier of the device
          type: string
          required: true
      responses:
        204:
          description: Success
        400:
          description: 'Failed to delete account, error code: CRE000074'
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: 'Full authentication is required.'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: CRE000003'
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: 'Internal server error, error code: CRE900001'
          schema:
            $ref: '#/definitions/ErrorResponse'

definitions:
  QrEnrolRequest:
    type: object
    required:
      - user_id
    properties:
      user_id:
        type: string
        pattern: ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{12}$
        description: The id of the user.
      format:
        type: string
        enum:
          - raw
          - png
        default: png

  QrEnrolResponse:
    type: object
    properties:
      qr_code:
        type: string
        format: byte
        description: >-
          Byte array representing the generated QR code.
      nonce:
        type: string
        description: >-
          The generated nonce when generation a QR code.
          The nonce will be stored for 24 hours.
      validity_period:
        type: integer
        description: Specifies the allowable elapsed time in seconds since the End-User can scan the QR code.
  EnrolmentStatusResponse:
    type: object
    properties:
      userId:
        type: string
      status:
        type: string
        enum:
          - enrolled
          - pending
          - failed
          - timeout
  NotificationStatusResponse:
    type: object
    properties:
      userId:
        type: string
      accountId:
        type: integer
      status:
        type: string
        enum:
          - confirmed
          - pending
          - timeout
          - declined
  PushNotificationRequest:
    type: object
    required:
      - message
    properties:
      message:
        type: string
        description: Represents the message that will be displayed on the push notification on user’s device.
  PushNotificationResponse:
    type: object
    properties:
      validity_period:
        type: integer
        description: Specifies the allowable elapsed time in seconds since the End-User can confirm the push notification.
  UserDeviceResponse:
    type: object
    properties:
      id:
        type: string
        description: Identifier of the device
      created:
        type: integer
        format: int64
        description: Timestamp when the device was registered
      lastLogin:
        type: integer
        format: int64
        description: Timestamp of the last login using a device
      metadata:
        type: object
        description: Provides other device information

  ErrorResponse:
    type: object
    properties:
      error_code:
        type: string
        enum:
          - CRE000064
          - CRE000065
          - CRE000066
          - CRE000067
          - CRE000068
          - CRE000069
          - CRE000070
          - CRE000071
          - CRE000072
          - CRE000074
          - CRE000075
          - CRE000101
          - CRE000102
          - CRE000103
          - CRE000104
          - CRE900001
          - CRE900005
        description: |
          Error code:
            * CRE000064: Failed to retrieve authentication state.
            * CRE000065: Invalid nonce or expired.
            * CRE000066: Failed to create enrol QrCode.
            * CRE000067: Missing request header.
            * CRE000068: Failed to create login QrCode.
            * CRE000069: Failed to push user notification.
            * CRE000070: Failed to push notification.
            * CRE000071: Failed to retrieve notification.
            * CRE000072: Failed to push account notification.
            * CRE000074: Failed to delete device.
            * CRE000075: Failed to delete user devices.
            * CRE000101: Bad request.
            * CRE000102: Access token is valid but doesn't have the right scope.
            * CRE000103: No valid access token.
            * CRE000104: The specified user does not exist.
            * CRE900001: Internal Server Error
            * CRE900005: Argument not valid
      description:
        type: string
        description: Detailed error message
      message:
        type: string
        description: Error message
