Schlage Home API — Devices

naftiko: 1.0.0-alpha2
info:
  label: Schlage Home API — Devices
  description: 'Schlage Home API — Devices. 5 operations covering list, get, update, lock,
    and unlock for Schlage Encode WiFi residential smart locks. Uses OAuth 2.0 against
    account.schlage.com and the asynchronous 202 ACCEPTED command pattern. Self-contained
    Naftiko capability covering one Allegion business surface.'
  tags:
    - Allegion
    - Schlage Home
    - Devices
    - Smart Lock
    - WiFi
    - OAuth
  created: '2026-05-23'
  modified: '2026-05-23'
binds:
  - namespace: env
    keys:
      SCHLAGE_HOME_ACCESS_TOKEN: SCHLAGE_HOME_ACCESS_TOKEN
capability:
  consumes:
    - type: http
      namespace: schlage-home-devices
      baseUri: https://api.allegion.com/schlage-home
      description: Schlage Home API — Devices business capability. Self-contained, no shared references.
      resources:
        - name: devices
          path: /devices
          operations:
            - name: listDevices
              method: GET
              description: List Schlage Home WiFi smart locks the user has authorized for this integration.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: device
          path: /devices/{deviceId}
          operations:
            - name: getDevice
              method: GET
              description: Get a single Schlage Home device including lock state, battery, WiFi signal strength, and firmware.
              inputParameters:
                - name: deviceId
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: updateDevice
              method: PUT
              description: Update device configuration (asynchronous - returns 202 ACCEPTED + commandId).
              inputParameters:
                - name: deviceId
                  in: path
                  type: string
                  required: true
                - name: body
                  in: body
                  type: object
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: deviceLock
          path: /devices/{deviceId}/lock
          operations:
            - name: lockDevice
              method: POST
              description: Issue an asynchronous lock command (202 ACCEPTED).
              inputParameters:
                - name: deviceId
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: deviceUnlock
          path: /devices/{deviceId}/unlock
          operations:
            - name: unlockDevice
              method: POST
              description: Issue an asynchronous unlock command (202 ACCEPTED).
              inputParameters:
                - name: deviceId
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
      authentication:
        type: bearer
        token: '{{env.SCHLAGE_HOME_ACCESS_TOKEN}}'
  exposes:
    - type: rest
      namespace: schlage-home-devices-rest
      port: 8080
      description: REST adapter for Schlage Home Devices. One Spectral-compliant resource per consumed operation, prefixed with /v1.
      resources:
        - path: /v1/devices
          name: devices
          description: REST surface for listDevices.
          operations:
            - method: GET
              name: listDevices
              description: List Devices
              call: schlage-home-devices.listDevices
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/devices/{deviceId}
          name: device
          description: REST surface for getDevice and updateDevice.
          operations:
            - method: GET
              name: getDevice
              description: Get Device
              call: schlage-home-devices.getDevice
              with:
                deviceId: rest.deviceId
              outputParameters:
                - type: object
                  mapping: $.
            - method: PUT
              name: updateDevice
              description: Update Device
              call: schlage-home-devices.updateDevice
              with:
                deviceId: rest.deviceId
                body: rest.body
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/devices/{deviceId}/lock
          name: lock
          description: REST surface for lockDevice.
          operations:
            - method: POST
              name: lockDevice
              description: Lock Device
              call: schlage-home-devices.lockDevice
              with:
                deviceId: rest.deviceId
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/devices/{deviceId}/unlock
          name: unlock
          description: REST surface for unlockDevice.
          operations:
            - method: POST
              name: unlockDevice
              description: Unlock Device
              call: schlage-home-devices.unlockDevice
              with:
                deviceId: rest.deviceId
              outputParameters:
                - type: object
                  mapping: $.