ButterflyMX

ButterflyMX Virtual Keys API

The Virtual Keys API from ButterflyMX — 2 operation(s) for virtual keys.

GitHub OpenAPI

Documentation

📖
Documentation
https://apidocs.butterflymx.com/
📖
APIReference
https://apidocs.butterflymx.com/reference/get_v4-buildings-1
📖
GettingStarted
https://apidocs.butterflymx.com/docs/getting-started-in-the-sandbox
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/butterflymx/refs/heads/main/authentication/butterflymx-authentication.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/butterflymx/refs/heads/main/openapi/butterflymx-virtual-keys-api-openapi.yml

Other Resources

🔗
OAuthScopes
https://raw.githubusercontent.com/api-evangelist/butterflymx/refs/heads/main/scopes/butterflymx-scopes.yml
🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/butterflymx/refs/heads/main/conventions/butterflymx-conventions.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/butterflymx/refs/heads/main/errors/butterflymx-problem-types.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/butterflymx/refs/heads/main/data-model/butterflymx-data-model.yml
🔗
Webhooks
https://raw.githubusercontent.com/api-evangelist/butterflymx/refs/heads/main/asyncapi/butterflymx-webhooks.yml
🔗
Sandbox
https://raw.githubusercontent.com/api-evangelist/butterflymx/refs/heads/main/sandbox/butterflymx-sandbox.yml

OpenAPI Specification

butterflymx-virtual-keys-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: ButterflyMX Virtual Keys API
  version: v4
servers:
- description: Production
  url: https://api.butterflymx.com
- description: Sandbox
  url: https://api.na.sandbox.butterflymx.com
- description: Other environment
  url: https://{environment_name}.butterflymx.com
  variables:
    environment_name:
      default: foobar
tags:
- name: Virtual Keys
paths:
  /v4/virtual_keys:
    get:
      summary: list virtual keys
      tags:
      - Virtual Keys
      description: '**Virtual keys** provide temporary access to guests. Please see the

        **Keychain** documentation for more details.


        A guest can be sent a Virtual Key via email or via SMS.

        '
      security:
      - Bearer: []
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          minimum: 0
        description: requested page
        example: 3
      - name: per
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
        description: page size
        example: 50
      - name: q[name_eq]
        in: query
        description: filter by exact match on name (case insensitive)
        example: George
        schema:
          type: string
      - name: q[name_start]
        in: query
        description: filter by name starts with (case insensitive)
        example: Ge
        schema:
          type: string
      - name: q[email_eq]
        in: query
        description: filter by exact match on email (case insensitive)
        example: george@example.com
        schema:
          type: string
      - name: q[email_start]
        in: query
        description: filter by email starts with (case insensitive)
        example: george@
        schema:
          type: string
      - name: q[sms_number_eq]
        in: query
        description: filter by exact match on SMS number (case insensitive)
        example: '+12345678900'
        schema:
          type: string
      - name: q[sms_number_start]
        in: query
        description: filter by SMS number starts with (case insensitive)
        example: '+123'
        schema:
          type: string
      - name: q[keychain_id_eq]
        in: query
        description: filter by exact match on keychain id
        example: 123
        schema:
          type: string
      - name: q[keychain_id_in][]
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            type: integer
        description: filter by keychain id in list
        example:
        - 123
        - 456
      - name: q[building_id_eq]
        in: query
        description: filter by exact match on building id
        example: 123
        schema:
          type: string
      - name: q[building_id_in][]
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            type: integer
        description: filter by building id in list
        example:
        - 123
        - 456
      - name: q[id_in][]
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            type: integer
        description: filter by id in list
        example:
        - 123
        - 456
      responses:
        '200':
          description: fetch all virtual keys that your user can see
          content:
            application/json:
              examples:
                fetch all virtual keys that your user can see:
                  value:
                    data:
                    - created_at: '2026-06-17T15:12:20Z'
                      email: visitor-1@atreides.org
                      first_used_at: '2026-06-14T15:12:20Z'
                      id: 1035872582
                      keychain_id: 940364922
                      last_used_at: '2026-06-14T15:12:20Z'
                      name: Visitor 1
                      sent_at: '2026-05-17T15:12:20Z'
                      sms_number: null
                      updated_at: '2026-06-17T15:12:20Z'
                      usage_count: 1
                      qr_code_url: http://user.butterflymx.localhosthttps://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1781709139-dbc88a23a0a2960f2afa01e1ddd1d737/store/medium/04.png
                      pin_code: null
                      building_id: 577696272
                      instructions_url: http://user.butterflymx.localhost/public/virtual_keys/1035872582/eec409f6-76ca-4089-b2e6-4a07a0de88e5
                    - created_at: '2026-06-17T15:12:20Z'
                      email: visitor-2@example.com
                      first_used_at: '2026-06-14T15:12:20Z'
                      id: 616003833
                      keychain_id: 254331397
                      last_used_at: '2026-06-14T15:12:20Z'
                      name: Visitor 2
                      sent_at: '2026-05-17T15:12:20Z'
                      sms_number: null
                      updated_at: '2026-06-17T15:12:20Z'
                      usage_count: 1
                      qr_code_url: http://user.butterflymx.localhosthttps://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1781709139-dbc88a23a0a2960f2afa01e1ddd1d737/store/medium/01.png
                      pin_code: null
                      building_id: 577696272
                      instructions_url: http://user.butterflymx.localhost/public/virtual_keys/616003833/0423aed0-2188-4703-9b14-86b5f08e111d
                    - created_at: '2026-06-13T15:12:20Z'
                      email: visitor-1@example.com
                      first_used_at: '2026-06-14T15:12:20Z'
                      id: 1035872581
                      keychain_id: 254331397
                      last_used_at: '2026-06-14T15:12:20Z'
                      name: Visitor 1
                      sent_at: '2026-05-17T15:12:20Z'
                      sms_number: null
                      updated_at: '2026-06-17T15:12:20Z'
                      usage_count: 1
                      qr_code_url: http://user.butterflymx.localhosthttps://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1781709139-dbc88a23a0a2960f2afa01e1ddd1d737/store/medium/02.png
                      pin_code: '683103'
                      building_id: 577696272
                      instructions_url: http://user.butterflymx.localhost/public/virtual_keys/1035872581/1f05f3f5-1809-4db3-adb9-ccd05e71b6ca
                    - created_at: '2026-06-13T15:12:20Z'
                      email: visitor-5@example.com
                      first_used_at: null
                      id: 1012402508
                      keychain_id: 494234073
                      last_used_at: null
                      name: Upcoming Visitor
                      sent_at: '2026-05-17T15:12:20Z'
                      sms_number: null
                      updated_at: '2026-06-17T15:12:20Z'
                      usage_count: 0
                      qr_code_url: http://user.butterflymx.localhosthttps://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1781709139-dbc88a23a0a2960f2afa01e1ddd1d737/store/medium/06.png
                      pin_code: '123450'
                      building_id: 750989427
                      instructions_url: http://user.butterflymx.localhost/public/virtual_keys/1012402508/db2941fe-8936-4191-b8e8-1e395e0a3977
                    - created_at: '2026-06-13T15:12:20Z'
                      email: visitor-4@example.com
                      first_used_at: '2026-06-14T15:12:20Z'
                      id: 948689649
                      keychain_id: 692527966
                      last_used_at: '2026-06-14T15:12:20Z'
                      name: Expired Visitor
                      sent_at: '2026-05-17T15:12:20Z'
                      sms_number: '1234567890'
                      updated_at: '2026-06-17T15:12:20Z'
                      usage_count: 1
                      qr_code_url: http://user.butterflymx.localhosthttps://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1781709139-dbc88a23a0a2960f2afa01e1ddd1d737/store/medium/06.png
                      pin_code: '123459'
                      building_id: 750989427
                      instructions_url: http://user.butterflymx.localhost/public/virtual_keys/948689649/9fc383e3-0434-48b6-9b6b-b2a65d029746
                    - created_at: '2026-06-13T15:12:20Z'
                      email: visitor-1@example.com
                      first_used_at: '2026-06-14T15:12:20Z'
                      id: 497669756
                      keychain_id: 803429365
                      last_used_at: '2026-06-14T15:12:20Z'
                      name: Active Visitor
                      sent_at: '2026-05-17T15:12:20Z'
                      sms_number: null
                      updated_at: '2026-06-17T15:12:20Z'
                      usage_count: 1
                      qr_code_url: http://user.butterflymx.localhosthttps://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1781709139-dbc88a23a0a2960f2afa01e1ddd1d737/store/medium/06.png
                      pin_code: '123456'
                      building_id: 750989427
                      instructions_url: http://user.butterflymx.localhost/public/virtual_keys/497669756/aecd4f96-6367-4f82-9ec2-aabbf9808472
                    page_info:
                      current_page: 1
                      total_pages: 1
                      total_item_count: 6
                      page_item_count: 6
                      page_size: 50
                      next_page: null
                      prev_page: null
                      first_page: true
                      last_page: true
        '401':
          description: unauthorized
          content:
            application/json:
              examples:
                unauthorized:
                  value:
                    errors:
                    - field: base
                      code: unauthorized
                      messages: Unauthorized
    post:
      summary: create virtual key
      tags:
      - Virtual Keys
      security:
      - Bearer: []
      parameters: []
      responses:
        '201':
          description: created with a recipient and a PIN code
          content:
            application/json:
              examples:
                created with email:
                  value:
                    data:
                      created_at: '2026-06-17T15:12:28Z'
                      email: foo@example.com
                      first_used_at: null
                      id: 1035872627
                      keychain_id: 254331397
                      last_used_at: null
                      name: D&D Game Night
                      sent_at: null
                      sms_number: null
                      updated_at: '2026-06-17T15:12:28Z'
                      usage_count: 0
                      qr_code_url: http://user.butterflymx.localhosthttps://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1781709139-dbc88a23a0a2960f2afa01e1ddd1d737/store/medium/qr_code_20260617-38996-sjgudw.png
                      pin_code: '319895'
                      building_id: 577696272
                      instructions_url: http://user.butterflymx.localhost/public/virtual_keys/1035872627/33d30311bfd882a84ec2d177ec1cf658
                created with  SMS number:
                  value:
                    data:
                      created_at: '2026-06-17T15:12:28Z'
                      email: null
                      first_used_at: null
                      id: 1035872628
                      keychain_id: 254331397
                      last_used_at: null
                      name: D&D Game Night
                      sent_at: null
                      sms_number: '+12345678900'
                      updated_at: '2026-06-17T15:12:28Z'
                      usage_count: 0
                      qr_code_url: http://user.butterflymx.localhosthttps://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1781709139-dbc88a23a0a2960f2afa01e1ddd1d737/store/medium/qr_code_20260617-38996-a2b8m8.png
                      pin_code: '313591'
                      building_id: 577696272
                      instructions_url: http://user.butterflymx.localhost/public/virtual_keys/1035872628/fd77585f4bcbf3844c47b8ef7f166f5f
                created without a recipient but with a PIN code:
                  value:
                    data:
                      created_at: '2026-06-17T15:12:28Z'
                      email: null
                      first_used_at: null
                      id: 1035872629
                      keychain_id: 254331397
                      last_used_at: null
                      name: D&D Game Night
                      sent_at: null
                      sms_number: null
                      updated_at: '2026-06-17T15:12:28Z'
                      usage_count: 0
                      qr_code_url: http://user.butterflymx.localhosthttps://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1781709139-dbc88a23a0a2960f2afa01e1ddd1d737/store/medium/qr_code_20260617-38996-eabzqm.png
                      pin_code: '468931'
                      building_id: 577696272
                      instructions_url: http://user.butterflymx.localhost/public/virtual_keys/1035872629/656cb6c2b647bb8bc6563d3f6d9e7d42
                created with a recipient and a PIN code:
                  value:
                    data:
                      created_at: '2026-06-17T15:12:28Z'
                      email: john.doe@example.com
                      first_used_at: null
                      id: 1035872631
                      keychain_id: 254331397
                      last_used_at: null
                      name: John Doe
                      sent_at: null
                      sms_number: null
                      updated_at: '2026-06-17T15:12:28Z'
                      usage_count: 0
                      qr_code_url: http://user.butterflymx.localhosthttps://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1781709139-dbc88a23a0a2960f2afa01e1ddd1d737/store/medium/qr_code_20260617-38996-k49chu.png
                      pin_code: '468931'
                      building_id: 577696272
                      instructions_url: http://user.butterflymx.localhost/public/virtual_keys/1035872631/786fb8fed2890a418599bc9feb46b6eb
        '422':
          description: returns an error if the PIN is too weak
          content:
            application/json:
              examples:
                returns an error if the PIN is too weak:
                  value:
                    errors:
                    - field: code
                      message: isn't strong enough, try a different value
                      code: low_entropy
                    - field: code
                      message: is the wrong length (should be 6 characters)
                      code: wrong_length
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the key or the recipient of the key
                  example: John Doe
                email:
                  type: string
                  description: Email address to which the key should be sent
                  example: foo@example.com
                sms_number:
                  type: string
                  description: Phone number to which the key should be sent
                  example: '+12345678900'
                keychain_id:
                  type: integer
                  description: ID of the keychain to which to attach the key
                  example: 123
                pin_code:
                  type: string
                  description: PIN code to use for the key - leave blank to get a random PIN
                  example: '468931'
              required:
              - keychain_id
              additionalProperties: false
            examples:
              created with email:
                summary: created with email
                value:
                  keychain_id: 254331397
                  email: foo@example.com
              created with  SMS number:
                summary: created with  SMS number
                value:
                  keychain_id: 254331397
                  sms_number: '+12345678900'
              created without a recipient but with a PIN code:
                summary: created without a recipient but with a PIN code
                value:
                  keychain_id: 254331397
                  pin_code: '468931'
              returns an error if the PIN is too weak:
                summary: returns an error if the PIN is too weak
                value:
                  keychain_id: 254331397
                  pin_code: '1234'
              created with a recipient and a PIN code:
                summary: created with a recipient and a PIN code
                value:
                  keychain_id: 254331397
                  name: John Doe
                  email: john.doe@example.com
                  pin_code: '468931'
  /v4/virtual_keys/{id}:
    parameters:
    - name: id
      in: path
      description: id
      required: true
      schema:
        type: integer
    get:
      summary: show virtual keys
      tags:
      - Virtual Keys
      security:
      - Bearer: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    data:
                      created_at: '2026-06-13T15:12:20Z'
                      email: visitor-1@example.com
                      first_used_at: '2026-06-14T15:12:20Z'
                      id: 1035872581
                      keychain_id: 254331397
                      last_used_at: '2026-06-14T15:12:20Z'
                      name: Visitor 1
                      sent_at: '2026-05-17T15:12:20Z'
                      sms_number: null
                      updated_at: '2026-06-17T15:12:20Z'
                      usage_count: 1
                      qr_code_url: http://user.butterflymx.localhosthttps://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1781709139-dbc88a23a0a2960f2afa01e1ddd1d737/store/medium/02.png
                      pin_code: '683103'
                      building_id: 577696272
                      instructions_url: http://user.butterflymx.localhost/public/virtual_keys/1035872581/1f05f3f5-1809-4db3-adb9-ccd05e71b6ca
        '401':
          description: unauthorized
          content:
            application/json:
              examples:
                unauthorized:
                  value:
                    errors:
                    - field: base
                      code: unauthorized
                      messages: Unauthorized
    delete:
      summary: delete virtual key
      tags:
      - Virtual Keys
      security:
      - Bearer: []
      responses:
        '204':
          description: successful
        '401':
          description: unauthorized
          content:
            application/json:
              examples:
                unauthorized:
                  value:
                    errors:
                    - field: base
                      code: unauthorized
                      messages: Unauthorized
        '404':
          description: not found
          content:
            application/json:
              examples:
                not found:
                  value:
                    errors:
                    - field: base
                      code: not_found
                      message: Resource not found
        '422':
          description: unprocessable content
          content:
            application/json:
              examples:
                unprocessable content:
                  value:
                    errors:
                    - field: base
                      message: Failed to delete resource
                      code: failed_to_delete_resource
components:
  securitySchemes:
    Bearer:
      description: JWT necessary to make API calls
      type: apiKey
      name: Authorization
      in: header