KISI Role assignments API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Kisi Calendars Role assignments 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: Role assignments
paths:
  /role_assignments:
    get:
      operationId: fetchRoleAssignments
      summary: Fetch role assignments
      tags:
      - Role assignments
      security:
      - Kisi-Login: []
      - OAuth2: []
      parameters:
      - name: ids
        in: query
        schema:
          type: string
        description: Filter by object IDs
      - name: query
        in: query
        schema:
          type: string
        description: 'Filter by a freetext string. Properties searched: `user.email`, `user.name`

          '
      - name: limit
        in: query
        schema:
          type: integer
          default: 10
          maximum: 250
        description: The number of objects to return
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          maximum: 20000
        description: The number of objects to offset
      - name: role_id
        in: query
        schema:
          type: string
        description: Filter by role ID
      - name: assignee_type
        in: query
        schema:
          type: string
          enum:
          - User
          - Team
          - Guest
        description: Filter by assignee type
      - name: assignee_id
        in: query
        schema:
          type: integer
        description: Filter by assignee ID. Must be used with `assignee_type`
      - name: applies_to_type
        in: query
        schema:
          type: string
          enum:
          - Organization
          - Place
          - Group
        description: Filter by applies to type
      - name: applies_to_id
        in: query
        schema:
          type: integer
        description: Filter by applies to ID. Must be used with `applies_to_type`
      - name: scope
        deprecated: true
        in: query
        schema:
          type: string
          enum:
          - organization
          - place
          - group
          - team
        description: Filter by scope
      - name: user_id
        in: query
        schema:
          type:
          - integer
          - string
        description: Filter by user ID or by current user if value is `me`.
        deprecated: true
      - name: place_id
        in: query
        schema:
          type: integer
        description: Filter by place ID
        deprecated: true
      - name: group_id
        in: query
        schema:
          type: integer
        description: Filter by group ID
        deprecated: true
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - user.name
          - -user.name
        description: 'Sort the results. Prepend `-` to sort in reverse order.

          `user.name` - sort by user name, alphabetically

          '
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  oneOf:
                  - type: object
                    title: Organization Role Assignment
                    properties:
                      id:
                        type: integer
                        description: The ID of the role assignment
                      resource_type:
                        type: string
                        description: The resource type of the role assignment
                        const: RoleAssignment
                      created_at:
                        type: string
                        format: date-time
                        description: When the role assignment was created
                      updated_at:
                        type: string
                        format: date-time
                        description: When the role assignment was updated
                      role_id:
                        type: string
                        description: The role ID of the role assignment.
                      notify:
                        type: boolean
                        description: Whether an email should be sent to the user when this role assignment is created or updated.
                      applies_to_type:
                        type: string
                        const: Organization
                      applies_to_id:
                        type: integer
                        description: The applies_to ID of the role assignment
                      applies_to:
                        type: object
                        description: The applies_to of the role assignment
                        oneOf:
                        - type: object
                          title: Organization
                          properties:
                            id:
                              type: integer
                              description: The ID of the organization
                            resource_type:
                              type: string
                              description: The resource type of the organization
                              const: Organization
                            name:
                              type: string
                              description: The name of the organization
                            domain:
                              type: string
                              description: The domain of the organization.
                          required:
                          - id
                          - resource_type
                          - name
                          - domain
                          additionalProperties: false
                        - type: object
                          title: Place
                          properties:
                            id:
                              type: integer
                              description: The ID of the place
                            resource_type:
                              type: string
                              description: The resource type of the place
                              const: Place
                            name:
                              type: string
                              description: The name of the place
                          required:
                          - id
                          - resource_type
                          - name
                          additionalProperties: false
                        - type: object
                          title: Group
                          properties:
                            id:
                              type: integer
                              description: The ID of the group
                            resource_type:
                              type: string
                              description: The resource type of the group
                              const: Group
                            name:
                              type: string
                              description: The name of the group
                          required:
                          - id
                          - resource_type
                          - name
                          additionalProperties: false
                      assignee_type:
                        type: string
                        enum:
                        - User
                        - Team
                        - Guest
                        description: The assignee type of the role assignment
                      assignee_id:
                        type: integer
                        description: The assignee ID of the role assignment
                      assignee:
                        type: object
                        description: The assignee of the role assignment
                        oneOf:
                        - type: object
                          title: User
                          properties:
                            id:
                              type: integer
                              description: The ID of the user
                            resource_type:
                              type: string
                              description: The resource type of the user
                              const: User
                            email:
                              type: string
                              format: email
                              description: The email of the user.
                            name:
                              type: string
                              description: The name of the user
                          required:
                          - id
                          - resource_type
                          - email
                          - name
                          additionalProperties: false
                        - type: object
                          title: Team
                          properties:
                            id:
                              type: integer
                              description: The ID of the team
                            resource_type:
                              type: string
                              description: The resource type of the team
                              const: Team
                            name:
                              type: string
                              description: The name of the team
                          required:
                          - id
                          - resource_type
                          - name
                          additionalProperties: false
                        - type: object
                          title: Guest
                          properties:
                            id:
                              type: integer
                              description: The ID of the guest
                            resource_type:
                              type: string
                              description: The resource type of the guest
                              const: Guest
                            name:
                              type: string
                              description: The name of the guest
                            email:
                              type:
                              - string
                              - 'null'
                              format: email
                              description: The email of the guest.
                            phone_number:
                              type:
                              - string
                              - 'null'
                              description: 'The phone number of the guest. Only US, Canadian and Puerto Rican numbers in the format +11234567890 (E.164) are accepted.

                                '
                          required:
                          - id
                          - resource_type
                          - name
                          - email
                          - phone_number
                          additionalProperties: false
                      created_by_type:
                        type:
                        - string
                        - 'null'
                        enum:
                        - null
                        - User
                        - MarketplaceInstallation
                        description: The created_by type of the role assignment
                      created_by_id:
                        type:
                        - integer
                        - 'null'
                        description: The created_by ID of the role assignment
                      user_id:
                        type:
                        - integer
                        - 'null'
                        description: The user ID of the role assignment
                        deprecated: true
                      user:
                        type: object
                        title: User
                        description: The user of the role assignment
                        deprecated: true
                        properties:
                          id:
                            type: integer
                            description: The ID of the user
                          resource_type:
                            type: string
                            description: The resource type of the user
                            const: User
                          email:
                            type: string
                            format: email
                            description: The email of the user.
                          name:
                            type: string
                            description: The name of the user
                        required:
                        - id
                        - resource_type
                        - email
                        - name
                        additionalProperties: false
                      assignee_team_id:
                        type:
                        - integer
                        - 'null'
                        description: The assignee_team ID of the role assignment
                        deprecated: true
                      assignee_team:
                        type: object
                        title: Team
                        description: The assignee_team of the role assignment
                        deprecated: true
                        properties:
                          id:
                            type: integer
                            description: The ID of the team
                          resource_type:
                            type: string
                            description: The resource type of the team
                            const: Team
                          name:
                            type: string
                            description: The name of the team
                        required:
                        - id
                        - resource_type
                        - name
                        additionalProperties: false
                      guest_id:
                        type:
                        - integer
                        - 'null'
                        description: The guest ID of the role assignment
                        deprecated: true
                      guest:
                        type: object
                        title: Guest
                        description: The guest of the role assignment
                        deprecated: true
                        properties:
                          id:
                            type: integer
                            description: The ID of the guest
                          resource_type:
                            type: string
                            description: The resource type of the guest
                            const: Guest
                          name:
                            type: string
                            description: The name of the guest
                          email:
                            type:
                            - string
                            - 'null'
                            format: email
                            description: The email of the guest.
                          phone_number:
                            type:
                            - string
                            - 'null'
                            description: 'The phone number of the guest. Only US, Canadian and Puerto Rican numbers in the format +11234567890 (E.164) are accepted.

                              '
                        required:
                        - id
                        - resource_type
                        - name
                        - email
                        - phone_number
                        additionalProperties: false
                      issued_by_id:
                        type:
                        - integer
                        - 'null'
                        description: The user ID of the user who created the role assignment.
                        deprecated: true
                      type:
                        type: string
                        const: organization
                        deprecated: true
                      scope:
                        type: string
                        const: organization
                        deprecated: true
                      organization_id:
                        type: integer
                        description: The organization ID of the role assignment
                        deprecated: true
                      organization:
                        type: object
                        title: Organization
                        description: The organization of the role assignment
                        deprecated: true
                        properties:
                          id:
                            type: integer
                            description: The ID of the organization
                          resource_type:
                            type: string
                            description: The resource type of the organization
                            const: Organization
                          name:
                            type: string
                            description: The name of the organization
                          domain:
                            type: string
                            description: The domain of the organization.
                        required:
                        - id
                        - resource_type
                        - name
                        - domain
                        additionalProperties: false
                    required:
                    - id
                    - resource_type
                    - created_at
                    - updated_at
                    - role_id
                    - notify
                    - applies_to_type
                    - applies_to_id
                    - applies_to
                    - assignee_type
                    - assignee_id
                    - assignee
                    - created_by_type
                    - created_by_id
                    - user_id
                    - assignee_team_id
                    - guest_id
                    - issued_by_id
                    - type
                    - scope
                    - organization_id
                    - organization
                    additionalProperties: false
                  - type: object
                    title: Place Role Assignment
                    properties:
                      id:
                        type: integer
                        description: The ID of the role assignment
                      resource_type:
                        type: string
                        description: The resource type of the role assignment
                        const: RoleAssignment
                      created_at:
                        type: string
                        format: date-time
                        description: When the role assignment was created
                      updated_at:
                        type: string
                        format: date-time
                        description: When the role assignment was updated
                      role_id:
                        type: string
                        description: The role ID of the role assignment.
                      notify:
                        type: boolean
                        description: Whether an email should be sent to the user when this role assignment is created or updated.
                      applies_to_type:
                        type: string
                        const: Place
                      applies_to_id:
                        type: integer
                        description: The applies_to ID of the role assignment
                      applies_to:
                        type: object
                        description: The applies_to of the role assignment
                        oneOf:
                        - type: object
                          title: Organization
                          properties:
                            id:
                              type: integer
                              description: The ID of the organization
                            resource_type:
                              type: string
                              description: The resource type of the organization
                              const: Organization
                            name:
                              type: string
                              description: The name of the organization
                            domain:
                              type: string
                              description: The domain of the organization.
                          required:
                          - id
                          - resource_type
                          - name
                          - domain
                          additionalProperties: false
                        - type: object
                          title: Place
                          properties:
                            id:
                              type: integer
                              description: The ID of the place
                            resource_type:
                              type: string
                              description: The resource type of the 

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