openapi: 3.0.3
info:
  title: ENGAGE Cloud Credentialing API
  version: '1.0'
  description: |
    REST API hosted on the Allegion Device Management and Mobile Access Cloud
    (Engage Cloud) for managing BLE Mobile Credentials that unlock ENGAGE Gen 2
    Schlage hardware (Control B, NDEB, LEBMS/LEBMD locks; MTKB readers) and
    Von Duprin RU/RM exit devices.

    The Credentialing API performs functions to upload, delete, and get active
    lists of mobile credentials through the API, and is used by an Access
    Management Platform / Access Control System (ACS) to issue credentials that
    the Allegion BLE Mobile Access SDK then presents to hardware over Bluetooth.

    Authentication requires an `alle-subscription-key` header plus a Basic Auth
    token generated from ENGAGE credentials. Integrators must sign the Allegion
    Security Token Agreement before being granted access to the API or to the
    private GitHub repositories that contain the iOS and Android SDKs.

    Generated from public documentation at
    https://developer.allegion.com/en/products/schlage-mobile-credentials.
    Path naming is inferred from documented capability descriptions.
  contact:
    name: Allegion Developer Support
    url: https://developersupport.allegion.com/hc/en-us
  termsOfService: https://developer.allegion.com/en/products/schlage-mobile-credentials/how-to-integrate-schlage-ble-mobile-credentials-with-an-access-control-system.html
servers:
  - url: https://api.allegion.com/engage
    description: Production
tags:
  - name: Mobile Credentials
    description: Upload, delete, and list BLE Mobile Credentials for end users
  - name: Devices
    description: ENGAGE hardware discovery and commissioning (Allegion Device Communication SDK)
security:
  - SubscriptionKey: []
    BasicAuth: []
paths:
  /credentials:
    get:
      tags: [Mobile Credentials]
      summary: List Active Mobile Credentials
      description: Returns the active mobile credentials in the integrator's ENGAGE tenant.
      operationId: listCredentials
      parameters:
        - in: query
          name: userId
          schema: { type: string }
          description: Filter by ACS user identifier.
        - in: query
          name: status
          schema:
            type: string
            enum: [Active, Revoked, Expired]
      responses:
        '200':
          description: Credentials returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  credentials:
                    type: array
                    items:
                      $ref: '#/components/schemas/MobileCredential'
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      tags: [Mobile Credentials]
      summary: Upload Mobile Credential
      description: |
        Create (upload) a mobile credential for an ACS user. The credential is
        delivered to the user's mobile device by the Allegion BLE Mobile Access
        SDK and is then presented over BLE to authorized ENGAGE hardware.
      operationId: uploadCredential
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MobileCredentialCreate'
      responses:
        '201':
          description: Credential created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MobileCredential' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /credentials/{credentialId}:
    get:
      tags: [Mobile Credentials]
      summary: Get Mobile Credential
      operationId: getCredential
      parameters:
        - $ref: '#/components/parameters/CredentialId'
      responses:
        '200':
          description: Credential returned
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MobileCredential' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      tags: [Mobile Credentials]
      summary: Delete Mobile Credential
      description: Revoke (delete) a mobile credential. Subsequent unlock attempts using the credential will be denied.
      operationId: deleteCredential
      parameters:
        - $ref: '#/components/parameters/CredentialId'
      responses:
        '204':
          description: Credential revoked
        '404': { $ref: '#/components/responses/NotFound' }
  /devices:
    get:
      tags: [Devices]
      summary: List ENGAGE Devices
      description: List ENGAGE hardware enrolled in the integrator's tenant. Surfaces the inputs the Allegion Device Communication SDK uses for commissioning.
      operationId: listEngageDevices
      responses:
        '200':
          description: Devices returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  devices:
                    type: array
                    items:
                      $ref: '#/components/schemas/EngageDevice'
components:
  securitySchemes:
    SubscriptionKey:
      type: apiKey
      in: header
      name: alle-subscription-key
      description: Azure API Management subscription key issued via the Allegion Developer Portal.
    BasicAuth:
      type: http
      scheme: basic
      description: Basic Auth token generated from ENGAGE credentials.
  parameters:
    CredentialId:
      in: path
      name: credentialId
      required: true
      schema: { type: string }
  responses:
    Unauthorized:
      description: Missing or invalid subscription key / Basic Auth credentials.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: Credential not found in tenant.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    BadRequest:
      description: Request validation failed.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    MobileCredential:
      type: object
      properties:
        credentialId: { type: string }
        userId:
          type: string
          description: External (ACS) user identifier.
        userEmail: { type: string, format: email }
        userName: { type: string }
        status:
          type: string
          enum: [Active, Revoked, Expired]
        accessProfile:
          type: string
          description: Identifier of the ENGAGE access profile granted by this credential.
        validFrom: { type: string, format: date-time }
        validTo: { type: string, format: date-time }
        createdAt: { type: string, format: date-time }
        revokedAt: { type: string, format: date-time, nullable: true }
    MobileCredentialCreate:
      type: object
      required: [userId, accessProfile]
      properties:
        userId: { type: string }
        userEmail: { type: string, format: email }
        userName: { type: string }
        accessProfile: { type: string }
        validFrom: { type: string, format: date-time }
        validTo: { type: string, format: date-time }
    EngageDevice:
      type: object
      properties:
        deviceId: { type: string }
        name: { type: string }
        model:
          type: string
          enum: [BE467B, FE410B, NDEB, LEBMS, LEBMD, MTKB, XE360, CTE, VonDuprinRU, VonDuprinRM]
        firmwareVersion: { type: string }
        siteId: { type: string }
    Error:
      type: object
      properties:
        code: { type: string }
        message: { type: string }