openapi: 3.0.3
info:
  title: ENGAGE Cloud Credentialing Access Codes Mobile Credentials 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
security:
- SubscriptionKey: []
  BasicAuth: []
tags:
- name: Mobile Credentials
  description: Upload, delete, and list BLE Mobile Credentials for end users
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'
components:
  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
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  responses:
    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'
    Unauthorized:
      description: Missing or invalid subscription key / Basic Auth credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    CredentialId:
      in: path
      name: credentialId
      required: true
      schema:
        type: string
  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.