KISI Roles API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Kisi Calendars Roles API
  description: "## Introduction\n\nWelcome to the Kisi API documentation. Before you read further, please read\nthe general [Kisi Docs portal](https://docs.kisi.io/).\n\n<!-- theme: info -->\n> If you want to be notified by email about updates to our API, please subscribe to our\n> [newsletter](https://2e2bc.share.hsforms.com/2OsdqtC8xRHGQ2yaS16AF7w).\n\n### Format\n\nThe Kisi API supports JSON only, so please set `Accept` and `Content-Type`\nto `application/json`. All requests and responses will use JSON as the\nformat for any data encompassed in the body of requests and responses.\n\n```http\n<METHOD> <URL> HTTP/1.1\nAccept: application/json\nContent-Type: application/json\n```\n\n### Authentication\n\nMost calls to the API will require an authenticated user. If such a user\nis not present, you will receive a 401 response.\nFor more information about authentication, see the [Kisi Docs portal](https://docs.kisi.io/api/get_started/add_necessary_headers).\n\nAPI calls must be made using HTTPS. Any calls made over plain HTTP will fail.\n\n### Rate limits\n\nFor authenticated API requests, you can make up to 5 requests per second,\nper user. Note that the limit applies per user, so requests made using\ndifferent logins for the same user share the same quota.\n\nFor unauthenticated requests, you can make up to 5 requests per second, per\nIP address.\n\nThe following endpoints have custom rate limits:\n\n| Endpoint                   | Limit            |\n|----------------------------|------------------|\n| `POST /event_sets`         | 1 per second     |\n| `POST /signed_upload_urls` | 1 per 10 seconds |\n\nIf you exceed the rate limit, a 429 response will be returned.\n\nSome best practices:\n- If you're making requests for a single user, do so serially, *not* concurrently.\n- If you're making a large number of requests for a single user, wait at least one second between each request.\n\nWe reserve the right to change these limits as needed to ensure availability.\n\n### Deprecations\n\nIn the event that some part of the API has to be deprecated, we do the following:\n\n  1. Return the `Deprecation` header with the date of when the endpoint is deprecated.\n  2. Return the `Sunset` header with the date of when the endpoint can be expected to not function anymore.\n  3. When the `Sunset` date is reached, the endpoint may go away at any time.\n\nWe recommend listening to these headers to avoid disruptions.\n\n### Error codes\n\nSome endpoints return an error code and a message. In the table below all error codes are listed.\n\n| Error code | Message                                                                                         |\n|------------|-------------------------------------------------------------------------------------------------|\n| `afc507`   | The authentication link is not valid.                                                           |\n| `afc546`   | Invalid Two Factor backup code.                                                                 |\n| `faa9ff`   | The card is not activated.                                                                      |\n| `faa9ef`   | The card was not found.                                                                         |\n| `afc496`   | Access denied.                                                                                  |\n| `f29aef`   | Your link is invalid.                                                                           |\n| `afc516`   | Wrong email address or password.                                                                |\n| `afc536`   | Invalid Two Factor verification code.                                                           |\n| `afc526`   | Please provide a Two Factor verification code.                                                  |\n| `afc516`   | The two factor pin is invalid                                                                   |\n| `ffffff`   | An unexpected issue occured.                                                                    |\n| `fcd8ef`   | Access denied.                                                                                  |\n| `fcd8ff`   | Access disabled.                                                                                |\n| `cabbeb`   | A card with the same identifiers was already enrolled.                                          |\n| `bb4fff`   | Please authorize Kisi for Bluetooth.                                                            |\n| `bb5bff`   | No nearby Kisi reader found. Try enabling Bluetooth on your device.                             |\n| `bb4bff`   | Please enable Bluetooth.                                                                        |\n| `a7793f`   | Please authorize Kisi for location services.                                                    |\n| `a3799f`   | Please enable your location services.                                                           |\n| `a3793f`   | Please enable your location services.                                                           |\n| `f298cf`   | The place has disabled all links for you.                                                       |\n| `f298df`   | Your access rights for this place do not include links.                                         |\n| `f298bf`   | Your access right is invalid.                                                                   |\n| `f01337`   | Your group's access rights for this place do not include apps.                                  |\n| `34bd8f`   | Your device is not the primary one.                                                             |\n| `facced`   | Unable to decode the certificate.                                                               |\n| `bbb99f`   | Your location is not valid.                                                                     |\n| `bbb93f`   | The location of the lock is invalid.                                                            |\n| `a3995f`   | You are too far away.                                                                           |\n| `bb4faa`   | You're not close enough to the door.                                                            |\n| `bbc93f`   | In-app access is disabled by the organization. Please tap your phone against the reader.        |\n| `34ffaa`   | Your access is not allowed at this moment, please try again later.                              |\n| `f35ade`   | Your access is no longer valid.                                                                 |\n| `f398de`   | Your access is invalid.,                                                                        |\n| `f358de`   | Your access is not yet valid, please try again later.                                           |\n| `fad334`   | An error occurred permitting the the elevator stop.                                             |\n| `fad121`   | The elevator stop was not found.                                                                |\n| `fad122`   | The elevator stop was not configured.                                                           |\n| `fad123`   | The elevator stops are locked down.                                                             |\n| `fad124`   | The elevator stop was on schedule.                                                              |\n| `fad002`   | The place is currently locked down.                                                             |\n| `ff420a`   | The door has no assigned Kisi controller.                                                       |\n| `fad001`   | The door is currently locked down.                                                              |\n| `fad105`   | The door is improperly configured.                                                              |\n| `fad10e`   | The door could not be found.                                                                    |\n| `fad110`   | The door is already scheduled to be unlocked.                                                   |\n| `fad137`   | The access was denied by the zone.                                                              |\n| `fad146`   | The third party zone was overriden but it is still armed.                                       |\n| `fad10f`   | An error occurred connecting to the wireless lock.                                              |\n| `fad106`   | An error occurred finding the wireless lock.                                                    |\n| `fad107`   | The wireless lock is offline.                                                                   |\n| `fad112`   | An unlock is already in progress for the wireless lock.                                         |\n| `fac001`   | The Kisi controller is currently unavailable.                                                   |\n| `fac002`   | The Kisi controller is currently unavailable.                                                   |\n| `fac003`   | The Kisi device is currently unavailable.                                                       |\n| `fac004`   | The Kisi device is currently unavailable.                                                       |\n| `fad108`   | The Kisi controller is not yet configured.                                                      |\n| `ecc123`   | The Kisi controller encountered an unhandled error.                                             |\n| `fbc000`   | The Kisi controller firmware is being updated. This will take a few seconds. Please retry then. |\n| `aaa345`   | The zone has no assigned zone controller.                                                       |\n| `fad126`   | The zone could not be found.                                                                    |\n| `fad129`   | The alarm controller is currently unavailable.                                                  |\n| `adf234`   | An error occurred resetting the zone.                                                           |\n| `fad144`   | The third party alarm is still in violation.                                                    |\n| `abbb11`   | The integration partner experienced an error.                                                   |\n| `abcc11`   | An integration partner resource could not be found.                                             |\n| `abdd11`   | The communication with the integration partner failed.                                          |\n| `abee11`   | Authorization with the integration partner failed.                                              |\n| `abfe11`   | The integration is not acceptable                                                               |\n| `abff11`   | The integration is disabled.                                                                    |\n"
  contact:
    name: Kisi Support
    email: support@getkisi.com
servers:
- url: https://api.kisi.io
  description: Kisi Production
tags:
- name: Roles
paths:
  /roles:
    get:
      operationId: fetchRoles
      summary: Fetch roles
      tags:
      - Roles
      security:
      - Kisi-Login: []
      - OAuth2: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  title: Role
                  properties:
                    id:
                      type: string
                    resource_type:
                      type: string
                      description: The resource type of the role
                      const: Role
                    applies_to:
                      type: string
                      enum:
                      - Organization
                      - Place
                      - Group
                    name:
                      type: string
                    description:
                      type:
                      - string
                      - 'null'
                    custom:
                      type: boolean
                    permissions:
                      type: object
                      properties:
                        access_keys_read:
                          type: boolean
                        access_keys_write:
                          type: boolean
                        amenities_read:
                          type: boolean
                        amenities_write:
                          type: boolean
                        analytics_read:
                          type: boolean
                        apple_passes_read:
                          type: boolean
                        apple_passes_write:
                          type: boolean
                        bookings_read:
                          type: boolean
                        bookings_write:
                          type: boolean
                        camera_snapshot_sets_read:
                          type: boolean
                        camera_snapshots_read:
                          type: boolean
                        camera_snapshots_write:
                          type: boolean
                        cameras_read:
                          type: boolean
                        cameras_write:
                          type: boolean
                        capacities_read:
                          type: boolean
                        capacities_write:
                          type: boolean
                        card_assignments_read:
                          type: boolean
                        card_assignments_write:
                          type: boolean
                        cards_activate:
                          type: boolean
                        cards_read:
                          type: boolean
                        cards_write:
                          type: boolean
                        communication_policies_read:
                          type: boolean
                        communication_policies_write:
                          type: boolean
                        csv_card_import_read:
                          type: boolean
                        csv_card_import_write:
                          type: boolean
                        csv_user_import_read:
                          type: boolean
                        csv_user_import_write:
                          type: boolean
                        custom_roles_read:
                          type: boolean
                        custom_roles_write:
                          type: boolean
                        dashboards_read:
                          type: boolean
                        elevator_stops_permit:
                          type: boolean
                        elevator_stops_read:
                          type: boolean
                        elevator_stops_write:
                          type: boolean
                        elevators_read:
                          type: boolean
                        elevators_write:
                          type: boolean
                        event_retention_policies_read:
                          type: boolean
                        event_retention_policies_write:
                          type: boolean
                        events_read:
                          type: boolean
                        floors_read:
                          type: boolean
                        floors_write:
                          type: boolean
                        group_elevator_stops_read:
                          type: boolean
                        group_elevator_stops_write:
                          type: boolean
                        group_links_read:
                          type: boolean
                        group_links_write:
                          type: boolean
                        group_locks_read:
                          type: boolean
                        group_locks_write:
                          type: boolean
                        group_terminals_read:
                          type: boolean
                        group_terminals_write:
                          type: boolean
                        group_zones_read:
                          type: boolean
                        group_zones_write:
                          type: boolean
                        groups_read:
                          type: boolean
                        groups_write:
                          type: boolean
                        guests_read:
                          type: boolean
                        guests_write:
                          type: boolean
                        hardware_read:
                          type: boolean
                        hardware_write:
                          type: boolean
                        third_party_hf_uid_read_configurations_read:
                          type: boolean
                        third_party_hf_uid_read_configurations_write:
                          type: boolean
                        incident_occurrences_read:
                          type: boolean
                        incident_policies_read:
                          type: boolean
                        incident_policies_write:
                          type: boolean
                        incidents_read:
                          type: boolean
                        incidents_write:
                          type: boolean
                        integrations_read:
                          type: boolean
                        integrations_write:
                          type: boolean
                        intercom_assignment_read:
                          type: boolean
                        intercom_assignment_write:
                          type: boolean
                        intercom_completed_call_stream_read:
                          type: boolean
                        invites_write:
                          type: boolean
                        kiosk_shortcuts_read:
                          type: boolean
                        kiosk_shortcuts_write:
                          type: boolean
                        locks_read:
                          type: boolean
                        locks_unlock:
                          type: boolean
                        locks_write:
                          type: boolean
                        logins_read:
                          type: boolean
                        logins_write:
                          type: boolean
                        managed_devices_read:
                          type: boolean
                        managed_devices_write:
                          type: boolean
                        marketplace_app_shares_read:
                          type: boolean
                        marketplace_app_shares_write:
                          type: boolean
                        marketplace_installations_read:
                          type: boolean
                        marketplace_installations_write:
                          type: boolean
                        marketplace_shortcuts_read:
                          type: boolean
                        marketplace_shortcuts_write:
                          type: boolean
                        mobile_cache_policies_read:
                          type: boolean
                        mobile_cache_policies_write:
                          type: boolean
                        place_dashboard_read:
                          type: boolean
                        places_read:
                          type: boolean
                        places_write:
                          type: boolean
                        reports_read:
                          type: boolean
                        reports_write:
                          type: boolean
                        role_assignments_read:
                          type: boolean
                        role_assignments_write:
                          type: boolean
                        scanned_card_read:
                          type: boolean
                        scanned_card_write:
                          type: boolean
                        scheduled_report_read:
                          type: boolean
                        scheduled_report_write:
                          type: boolean
                        schedules_read:
                          type: boolean
                        schedules_write:
                          type: boolean
                        shares_read:
                          type: boolean
                        shares_write:
                          type: boolean
                        subscriptions_read:
                          type: boolean
                        team_memberships_read:
                          type: boolean
                        team_memberships_write:
                          type: boolean
                        teams_read:
                          type: boolean
                        teams_write:
                          type: boolean
                        terminals_read:
                          type: boolean
                        terminals_trigger:
                          type: boolean
                        terminals_write:
                          type: boolean
                        users_read:
                          type: boolean
                        users_write:
                          type: boolean
                        visualization_page_reporters_read:
                          type: boolean
                        visualization_page_reporters_write:
                          type: boolean
                        visualization_page_shares_read:
                          type: boolean
                        visualization_page_shares_write:
                          type: boolean
                        zones_override:
                          type: boolean
                        zones_read:
                          type: boolean
                        zones_reset:
                          type: boolean
                        zones_write:
                          type: boolean
                    custom_role_id:
                      type:
                      - integer
                      - 'null'
                      description: The custom_role ID of the role
                  required:
                  - id
                  - resource_type
                  - applies_to
                  - name
                  - description
                  - custom
                  - permissions
                  - custom_role_id
                  additionalProperties: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /roles/{id}:
    get:
      operationId: fetchRole
      summary: Fetch role
      tags:
      - Roles
      security:
      - Kisi-Login: []
      - OAuth2: []
      parameters:
      - name: id
        in: path
        schema:
          type: string
        required: true
        description: The ID of the object
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                title: Role
                properties:
                  id:
                    type: string
                  resource_type:
                    type: string
                    description: The resource type of the role
                    const: Role
                  applies_to:
                    type: string
                    enum:
                    - Organization
                    - Place
                    - Group
                  name:
                    type: string
                  description:
                    type:
                    - string
                    - 'null'
                  custom:
                    type: boolean
                  permissions:
                    type: object
                    properties:
                      access_keys_read:
                        type: boolean
                      access_keys_write:
                        type: boolean
                      amenities_read:
                        type: boolean
                      amenities_write:
                        type: boolean
                      analytics_read:
                        type: boolean
                      apple_passes_read:
                        type: boolean
                      apple_passes_write:
                        type: boolean
                      bookings_read:
                        type: boolean
                      bookings_write:
                        type: boolean
                      camera_snapshot_sets_read:
                        type: boolean
                      camera_snapshots_read:
                        type: boolean
                      camera_snapshots_write:
                        type: boolean
                      cameras_read:
                        type: boolean
                      cameras_write:
                        type: boolean
                      capacities_read:
                        type: boolean
                      capacities_write:
                        type: boolean
                      card_assignments_read:
                        type: boolean
                      card_assignments_write:
                        type: boolean
                      cards_activate:
                        type: boolean
                      cards_read:
                        type: boolean
                      cards_write:
                        type: boolean
                      communication_policies_read:
                        type: boolean
                      communication_policies_write:
                        type: boolean
                      csv_card_import_read:
                        type: boolean
                      csv_card_import_write:
                        type: boolean
                      csv_user_import_read:
                        type: boolean
                      csv_user_import_write:
                        type: boolean
                      custom_roles_read:
                        type: boolean
                      custom_roles_write:
                        type: boolean
                      dashboards_read:
                        type: boolean
                      elevator_stops_permit:
                        type: boolean
                      elevator_stops_read:
                        type: boolean
                      elevator_stops_write:
                        type: boolean
                      elevators_read:
                        type: boolean
                      elevators_write:
                        type: boolean
                      event_retention_policies_read:
                        type: boolean
                      event_retention_policies_write:
                        type: boolean
                      events_read:
                        type: boolean
                      floors_read:
                        type: boolean
                      floors_write:
                        type: boolean
                      group_elevator_stops_read:
                        type: boolean
                      group_elevator_stops_write:
                        type: boolean
                      group_links_read:
                        type: boolean
                      group_links_write:
                        type: boolean
                      group_locks_read:
                        type: boolean
                      group_locks_write:
                        type: boolean
                      group_terminals_read:
                        type: boolean
                      group_terminals_write:
                        type: boolean
                      group_zones_read:
                        type: boolean
                      group_zones_write:
                        type: boolean
                      groups_read:
                        type: boolean
                      groups_write:
                        type: boolean
                      guests_read:
                        type: boolean
                      guests_write:
                        type: boolean
                      hardware_read:
                        type: boolean
                      hardware_write:
                        type: boolean
                      third_party_hf_uid_read_configurations_read:
                        type: boolean
                      third_party_hf_uid_read_configurations_write:
                        type: boolean
                      incident_occurrences_read:
                        type: boolean
                      incident_policies_read:
                        type: boolean
                      incident_policies_write:
                        type: boolean
                      incidents_read:
                        type: boolean
                      incidents_write:
                        type: boolean
                      integrations_read:
                        type: boolean
                      integrations_write:
                        type: boolean
                      intercom_assignment_read:
                        type: boolean
                      intercom_assignment_write:
                        type: boolean
                      intercom_completed_call_stream_read:
                        type: boolean
                      invites_write:
                        type: boolean
                      kiosk_shortcuts_read:
                        type: boolean
                      kiosk_shortcuts_write:
                        type: boolean
                      locks_read:
                        type: boolean
                      locks_unlock:
                        type: boolean
                      locks_write:
                        type: boolean
                      logins_read:
                        type: boolean
                      logins_write:
                        type: boolean
                      managed_devices_read:
                        type: boolean
                      managed_devices_write:
                        type: boolean
                      marketplace_app_shares_read:
                        type: boolean
                      marketplace_app_shares_write:
                        type: boolean
                      marketplace_installations_read:
                        type: boolean
                      marketplace_installations_write:
                        type: boolean
                      marketplace_shortcuts_read:
                        type: boolean
                      marketplace_shortcuts_write:
                        type: boolean
                      mobile_cache_policies_read:
                        type: boolean
                      mobile_cache_policies_write:
                        type: boolean
                      place_dashboard_read:
                        type: boolean
                      places_read:
                        type: boolean
                      places_write:
                        type: boolean
                      reports_read:
                        type: boolean
                      reports_write:
                        type: boolean
                      role_assignments_read:
                        type: boolean
                      role_assignments_write:
                        type: boolean
                      scanned_card_read:
                        type: boolean
                      scanned_card_write:
                        type: boolean
                      scheduled_report_read:
                        type: boolean
                      scheduled_report_write:
                        type: boolean
                      schedules_read:
                        type: boolean
                      schedules_write:
                        type: boolean
                      shares_read:
                        type: boolean
                      shares_write:
                        type: boolean
                      subscriptions_read:
                        type: boolean
                      team_memberships_read:
                        type: boolean
                      team_memberships_write:
                        type: boolean
                      teams_read:
                        type: boolean
                      teams_write:
                        type: boolean
          

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kisi/refs/heads/main/openapi/kisi-roles-api-openapi.yml