KISI Organizations API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Kisi Calendars Organizations 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: Organizations
paths:
  /organizations:
    get:
      operationId: fetchOrganizations
      summary: Fetch organizations
      tags:
      - Organizations
      security:
      - Kisi-Login: []
      - OAuth2: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  oneOf:
                  - type: object
                    title: Organization - when authenticated by group link
                    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.
                      logo:
                        type:
                        - string
                        - 'null'
                        format: uri
                        description: The URL to the logo of the organization.
                      address:
                        type:
                        - string
                        - 'null'
                        description: The address of the organization.
                      description:
                        type:
                        - string
                        - 'null'
                        description: The description of the organization
                      time_zone:
                        type:
                        - string
                        example: Europe/London
                        description: 'The time zone of the organization.

                          It should be a <a href="https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones"> valid IANA time zone name.</a>

                          '
                      transfer_to_id:
                        type:
                        - integer
                        - 'null'
                        description: The transfer_to ID of the organization
                      transfer_to:
                        type: object
                        title: User
                        description: The transfer_to of the organization
                        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
                      image:
                        deprecated: true
                        type:
                        - string
                        - 'null'
                      color:
                        deprecated: true
                        type:
                        - string
                        - 'null'
                    required:
                    - id
                    - resource_type
                    - name
                    - domain
                    - logo
                    - address
                    - description
                    - time_zone
                    - transfer_to_id
                    - image
                    - color
                    additionalProperties: false
                  - 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.
                      logo:
                        type:
                        - string
                        - 'null'
                        format: uri
                        description: The URL to the logo of the organization.
                      address:
                        type:
                        - string
                        - 'null'
                        description: The address of the organization.
                      description:
                        type:
                        - string
                        - 'null'
                        description: The description of the organization
                      device_logins_expire_after:
                        type:
                        - integer
                        - 'null'
                        default: 1209600
                        minimum: 0
                        maximum: 31536000
                        description: 'The device login expiration in seconds.

                          If not defined, it defaults to 2 weeks of inactivity.

                          '
                      places_count:
                        type: integer
                        description: Count of all the places within the organization.
                      scim_enabled:
                        type: boolean
                        description: Whether SCIM is enabled for the organization.
                      sso_flow_enabled:
                        type: boolean
                        description: 'Whether the organization has SSO flow enabled. Mutually exclusive with password flow.

                          '
                      sso_expiration_override_enabled:
                        type: boolean
                        description: 'Whether the organization should override length of SSO session.

                          '
                      sso_expiration_override:
                        type:
                        - integer
                        - 'null'
                        description: 'The length of the SSO session (in seconds) that will override the default passed from Identity Provider.

                          '
                      metadata:
                        type:
                        - string
                        - 'null'
                        description: The SSO metadata of the organization.
                      time_zone:
                        type:
                        - string
                        example: Europe/London
                        description: 'The time zone of the organization.

                          It should be a <a href="https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones"> valid IANA time zone name.</a>

                          '
                      web_authentication_api_enabled:
                        type: boolean
                        description: 'Whether web authentication api is enabled.

                          Only for organizations using SSO and IdP authentication is done using WebAuthn.

                          '
                      apple_pass_enabled:
                        type: boolean
                        description: Whether Apple Pass is enabled for the organization.
                      created_at:
                        type: string
                        format: date-time
                        description: When the organization was created
                      updated_at:
                        type: string
                        format: date-time
                        description: When the organization was updated
                      user_id:
                        type:
                        - integer
                        - 'null'
                        description: The user ID of the organization
                      transfer_to_id:
                        type:
                        - integer
                        - 'null'
                        description: The transfer_to ID of the organization
                      transfer_to:
                        type: object
                        title: User
                        description: The transfer_to of the organization
                        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
                      image:
                        deprecated: true
                        type:
                        - string
                        - 'null'
                      color:
                        deprecated: true
                        type:
                        - string
                        - 'null'
                    required:
                    - id
                    - resource_type
                    - name
                    - domain
                    - logo
                    - address
                    - description
                    - device_logins_expire_after
                    - places_count
                    - scim_enabled
                    - sso_flow_enabled
                    - sso_expiration_override_enabled
                    - sso_expiration_override
                    - metadata
                    - time_zone
                    - web_authentication_api_enabled
                    - apple_pass_enabled
                    - created_at
                    - updated_at
                    - user_id
                    - transfer_to_id
                    - image
                    - color
                    additionalProperties: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /organizations/{domain}/public:
    get:
      operationId: fetchPublicOrganization
      summary: Fetch public organization
      tags:
      - Organizations
      parameters:
      - name: domain
        in: path
        schema:
          type: string
        required: true
        description: The domain of the organization.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                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.
                  places_count:
                    type: integer
                    description: Count of all the places within the organization.
                  logo:
                    type:
                    - string
                    - 'null'
                    format: uri
                    description: The URL to the logo of the organization.
                  sso_flow_enabled:
                    type: boolean
                    description: 'Whether the organization has SSO flow enabled. Mutually exclusive with password flow.

                      '
                  web_authentication_api_enabled:
                    type: boolean
                    description: 'Whether web authentication api is enabled.

                      Only for organizations using SSO and IdP authentication is done using WebAuthn.

                      '
                  image:
                    deprecated: true
                    type:
                    - string
                    - 'null'
                  color:
                    deprecated: true
                    type:
                    - string
                    - 'null'
                required:
                - id
                - resource_type
                - name
                - domain
                - places_count
                - logo
                - sso_flow_enabled
                - web_authentication_api_enabled
                - image
                - color
                additionalProperties: false
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /organizations/find:
    post:
      operationId: findOrganizations
      summary: Find my organizations
      description: Sends an email to the user including a list of all their organizations.
      tags:
      - Organizations
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  type: object
                  properties:
                    email:
                      type: string
                      format: email
                      description: The user's email.
                  required:
                  - email
              required:
              - user
      responses:
        '204':
          description: No Content
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /organization:
    get:
      operationId: fetchCurrentOrganization
      summary: Fetch current organization
      tags:
      - Organizations
      security:
      - Kisi-Login: []
      - Kisi-Group-Link: []
      - Kisi-Access-Key: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                oneOf:
                - type: object
                  title: Organization - when authenticated by group link
                  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.
                    logo:
                      type:
                      - string
                      - 'null'
                      format: uri
                      description: The URL to the logo of the organization.
                    address:
                      type:
                      - string
                      - 'null'
                      description: The address of the organization.
                    description:
                      type:
                      - string
                      - 'null'
                      description: The description of the organization
                    time_zone:
                      type:
                      - string
                      example: Europe/London
                      description: 'The time zone of the organization.

                        It should be a <a href="https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones"> valid IANA time zone name.</a>

                        '
                    transfer_to_id:
                      type:
                      - integer
                      - 'null'
                      description: The transfer_to ID of the organization
                    transfer_to:
                      type: object
                      title: User
                      description: The transfer_to of the organization
                      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
                    image:
                      deprecated: true
                      type:
                      - string
                      - 'null'
                    color:
                      deprecated: true
                      type:
                      - string
                      - 'null'
                  required:
                  - id
                  - resource_type
                  - name
                  - domain
                  - logo
                  - address
                  - description
                  - time_zone
                  - transfer_to_id
                  - image
                  - color
                  additionalProperties: false
                - 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.
                    logo:
                      type:
                      - string
                      - 'null'
                      format: uri
                      description: The URL to the logo of the organization.
                    address:
                      type:
                      - string
                      - 'null'
                      description: The address of the organization.
                    description:
                      type:
                      - string
                      - 'null'
                      description: The description of the organization
                    device_logins_expire_after:
                      type:
                      - integer
                      - 'null'
                      default: 1209600
                      minimum: 0
                      maximum: 31536000
                      description: 'The device login expiration in seconds.

                        If not defined, it defaults to 2 weeks of inactivity.

                        '
                    places_count:
                      type: integer
                      description: Count of all the places within the organization.
                    scim_enabled:
                      type: boolean
                      description: Whether SCIM is enabled for the organization.
                    sso_flow_enabled:
                      type: boolean
                      description: 'Whether the organization has SSO flow enabled. Mutually exclusive with password flow.

                        '
                    sso_expiration_override_enabled:
                      type: boolean
                      description: 'Whether the organization should override length of SSO session.

                        '
                    sso_expiration_override:
                      type:
                      - integer
                      - 'null'
        

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