KISI Logins API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Kisi Calendars Logins 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: Logins
paths:
  /logins:
    get:
      operationId: fetchLogins
      summary: Fetch logins
      tags:
      - Logins
      security:
      - Kisi-Login: []
      - OAuth2: []
      parameters:
      - name: ids
        in: query
        schema:
          type: string
        description: Filter by object IDs
      - name: user_id
        in: query
        schema:
          type:
          - integer
          - string
        description: Filter by user ID or by current user if value is `me`. If not used, it will default to `me`.
      - name: scope
        in: query
        schema:
          type: string
          enum:
          - me
          - all
          default: me
        deprecated: true
        description: 'Filter by the scope of the record. Deprecated, use `user_id=me` to scope the logins to the current user.

          '
      - 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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  title: Login
                  properties:
                    id:
                      type: integer
                      description: The ID of the login
                    created_at:
                      type: string
                      format: date-time
                      description: When the login was created
                    updated_at:
                      type: string
                      format: date-time
                      description: When the login was updated
                    type:
                      type: string
                      description: The type of the login.
                      enum:
                      - api
                      - device
                    name:
                      type:
                      - string
                      - 'null'
                      description: The name for the login.
                    primary:
                      type: boolean
                      description: Whether the login is the primary login.
                    expire:
                      type: boolean
                      default: true
                      description: Whether the login expires.
                    last_used_at:
                      type:
                      - string
                      - 'null'
                      format: date-time
                      description: When the login was last used.
                    device_brand:
                      type:
                      - string
                      - 'null'
                      description: The brand of the device.
                    device_model:
                      type:
                      - string
                      - 'null'
                      description: The model of the device.
                    os_name:
                      type:
                      - string
                      - 'null'
                      description: The name of the OS.
                    user_id:
                      type: integer
                      description: The user ID of the login
                    user:
                      type: object
                      title: User
                      description: The user of the login
                      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
                    app:
                      type: object
                      properties:
                        name:
                          type:
                          - string
                          - 'null'
                          deprecated: true
                        version:
                          type:
                          - string
                          - 'null'
                          deprecated: true
                    user_agent:
                      type: object
                      properties:
                        name:
                          type:
                          - string
                          - 'null'
                          deprecated: true
                        version:
                          type:
                          - string
                          - 'null'
                          deprecated: true
                    device:
                      type: object
                      properties:
                        brand:
                          type:
                          - string
                          - 'null'
                          deprecated: true
                        model:
                          type:
                          - string
                          - 'null'
                          deprecated: true
                    os:
                      type: object
                      properties:
                        name:
                          type:
                          - string
                          - 'null'
                          deprecated: true
                        version:
                          type:
                          - string
                          - 'null'
                          deprecated: true
                  required:
                  - id
                  - created_at
                  - updated_at
                  - type
                  - name
                  - primary
                  - expire
                  - last_used_at
                  - device_brand
                  - device_model
                  - os_name
                  - user_id
                  - user
                  - app
                  - user_agent
                  - device
                  - os
                  additionalProperties: false
          headers:
            X-Collection-Range:
              description: 'Pagination information for offset based pagination. `start-end` represents the range

                of items requested. `total` represents the total count of items. If there is a total

                of 15 items and an offset of 10 and limit of 10 is used, the resulting header is:

                `10-19/15`.

                '
              schema:
                type: string
                pattern: ^(?<start>\d+)-(?<end>\d+)/(?<total>\d+)$
              example: 0-9/200
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createLogin
      summary: Create login
      description: 'Organization members will be able to access this endpoint only if their organization has sso flow disabled.

        Organization owner can create API key (login) regardless of the enabled flow (SSO flow | password flow).

        There is a limit on the number of device and API logins a user can have. We allow a user to have up

        to 40 device logins and 10 API logins.

        When the device logins limit exceeded, the least recent used logins will be removed and if they were not used,

        we will use the creation time.

        When the API logins limit exceeded, the endpoint will return an error message on a new creation attempt.

        '
      tags:
      - Logins
      requestBody:
        content:
          application/json:
            schema:
              type: object
              title: Login
              properties:
                login:
                  type: object
                  description: Information about the login being created.
                  properties:
                    type:
                      type: string
                      description: The type of the login.
                      enum:
                      - api
                      - device
                    name:
                      type:
                      - string
                      - 'null'
                      description: The name for the login.
                    device_brand:
                      type:
                      - string
                      - 'null'
                      description: The brand of the device.
                    device_model:
                      type:
                      - string
                      - 'null'
                      description: The model of the device.
                    device_uid:
                      type:
                      - string
                      - 'null'
                      description: The uid of the device. This field is experimental and may change.
                    os_name:
                      type:
                      - string
                      - 'null'
                      description: The name of the OS.
                    push_token:
                      type: string
                      description: The push token of the login.
                    ios_voip_push_token:
                      type: string
                      description: Voice over IP push token for iOS devices..
                    email:
                      type: string
                      format: email
                      description: 'The email of the user to create the login for.

                        We do not allow creating API logins on behalf of other users.

                        Only logins with `type` set to `device` can be created on behalf of other users.

                        '
                    expire:
                      type: boolean
                      default: true
                      description: Whether the login expires.
                user:
                  type: object
                  description: Authentication information about the user making the request to create a login.
                  properties:
                    domain:
                      type: string
                      description: The domain of the organization of the user. Required when signing in with password.
                    email:
                      type: string
                      description: The email of the user. Required when signing in with password.
                    password:
                      type: string
                      description: The password of the user. Required when signing in with password.
                    authentication_info:
                      type: string
                      description: An authentication info token. Can be used as a substitute for domain, email and password.
                    otp_attempt:
                      type: string
                      description: A one time password. Required when two factor authentication is turned on.
              required:
              - login
              - user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                title: Login
                properties:
                  id:
                    type: integer
                    description: The ID of the login
                  created_at:
                    type: string
                    format: date-time
                    description: When the login was created
                  updated_at:
                    type: string
                    format: date-time
                    description: When the login was updated
                  type:
                    type: string
                    description: The type of the login.
                    enum:
                    - api
                    - device
                  name:
                    type:
                    - string
                    - 'null'
                    description: The name for the login.
                  primary:
                    type: boolean
                    description: Whether the login is the primary login.
                  expire:
                    type: boolean
                    default: true
                    description: Whether the login expires.
                  last_used_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    description: When the login was last used.
                  device_brand:
                    type:
                    - string
                    - 'null'
                    description: The brand of the device.
                  device_model:
                    type:
                    - string
                    - 'null'
                    description: The model of the device.
                  os_name:
                    type:
                    - string
                    - 'null'
                    description: The name of the OS.
                  user_id:
                    type: integer
                    description: The user ID of the login
                  user:
                    type: object
                    title: User
                    description: The user of the login
                    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
                  app:
                    type: object
                    properties:
                      name:
                        type:
                        - string
                        - 'null'
                        deprecated: true
                      version:
                        type:
                        - string
                        - 'null'
                        deprecated: true
                  user_agent:
                    type: object
                    properties:
                      name:
                        type:
                        - string
                        - 'null'
                        deprecated: true
                      version:
                        type:
                        - string
                        - 'null'
                        deprecated: true
                  device:
                    type: object
                    properties:
                      brand:
                        type:
                        - string
                        - 'null'
                        deprecated: true
                      model:
                        type:
                        - string
                        - 'null'
                        deprecated: true
                  os:
                    type: object
                    properties:
                      name:
                        type:
                        - string
                        - 'null'
                        deprecated: true
                      version:
                        type:
                        - string
                        - 'null'
                        deprecated: true
                  scram_credentials:
                    type:
                    - object
                    - 'null'
                    properties:
                      phone_key:
                        type: string
                        format: hex
                      online_certificate:
                        type: string
                        format: hex
                  secret:
                    type: string
                    description: 'The secret value used for authentication.

                      Returned when creating API logins;

                      Returned for device logins when resolving and creating logins.

                      '
                  authentication_token:
                    type: string
                    deprecated: true
                    description: Alias for secret
                  has_primary_device:
                    type: boolean
                    description: Whether the user has a primary device.
                  email:
                    type: string
                    format: email
                    description: The email of the user.
                  notifications_unread_count:
                    type: integer
                    minimum: 0
                    description: The count of unread notifications.
                  otp_required_for_login:
                    type: boolean
                    description: Whether OTP/2FA is required for login.
                  otp_enabled_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    description: When was the OTP/2FA enabled.
                  image:
                    type:
                    - string
                    - 'null'
                    format: uri
                    description: The url to the image of the user.
                  primary_login_exists:
                    type: boolean
                    description: Whether the user has a primary login.
                required:
                - id
                - created_at
                - updated_at
                - type
                - name
                - primary
                - expire
                - last_used_at
                - device_brand
                - device_model
                - os_name
                - user_id
                - user
                - app
                - user_agent
                - device
                - os
                - scram_credentials
                - secret
                - authentication_token
                - has_primary_device
                - email
                - notifications_unread_count
                - otp_required_for_login
                - otp_enabled_at
                - image
                - primary_login_exists
                additionalProperties: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /logins/{id}:
    delete:
      operationId: deleteLogin
      summary: Delete login
      tags:
      - Logins
      security:
      - Kisi-Login: []
      - OAuth2: []
      parameters:
      - name: id
        in: path
        schema:
          type: integer
        required: true
        description: The ID of the object
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /logins/{id}/promote:
    post:
      operationId: promoteLogin
      summary: Promote login
      description: 'Promote login to primary login. Demotes other primary logins.

        '
      tags:
      - Logins
      security:
      - Kisi-Login: []
      - OAuth2: []
      parameters:
      - name: id
        in: path
        schema:
          type: integer
        required: true
        description: The ID of the object
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '

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