1KEY Developers
API reference

Intercoms

Base URL https://api.1keyplatform.dev/v1. Every endpoint below is generated from the OpenAPI contract, which you can download as openapi.yaml.

Log in to send these requests to your organization from this page.

Intercoms

1Key Intercoms your organization owns: the entry consoles at buildings' doors. They share hubs' scopes.

GET /intercoms/{intercom_id}/enrollment-code

Read a 1Key intercom's enrollment code

Needs the intercoms:write scope.

The code to enter on the intercom's screen to enroll it: six digits, one use, for 24 hours. The same code until it's used or expires, then a new one. For an intercom managed in 1Key.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Responses

200 The code.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
409 conflict: the intercom is managed by 1Valet.
POST /intercoms/{intercom_id}/enrollment-code

Make a new enrollment code

Needs the intercoms:write scope.

A new code for a 1Key intercom, replacing the one before.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Responses

200 The code.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
409 conflict: the intercom is managed by 1Valet.
GET /intercoms/{intercom_id}/credentials

List an intercom's codes and cards

Needs the intercoms:read scope.

As the intercom holds them, for either management. A code is never returned; code_hint is its last two digits.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Responses

200 The credentials.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
POST /intercoms/{intercom_id}/credentials

Add a code, card or face

Needs the intercoms:write scope.

For an intercom managed in 1Key. A card's number is stored as the decimal number the intercom reads. A face needs photos and consent: 1Key computes an embedding from each photo with the intercom's face model, keeps only the embeddings, and refuses the face if a photo isn't good enough (422 face_rejected).

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Body

card_format "decimal" | "wiegand26" | "hex" | "hex_reversed" · optional
code string · optional A pin: 4 to 10 digits. A card: decimal, facility:card (Wiegand 26-bit) or a hex UID. Only when adding.
consent boolean · optional A face: the person agreed to their face being used to open this door. Only when adding.
enabled boolean, default true · optional
entry_id integer or null · optional
kind "pin" | "card" | "face" · optional
label string or null · optional
photos array of string · optional A face: JPEGs of the face, 112 to 4,096 pixels on each side, at most 90,000 bytes in all. Only when adding; not stored.
schedule AccessSchedule or null · optional
type "general" | "disposable" · optional

Responses

200 The credential, without its code. · returns a IntercomCredential

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
409 conflict: the intercom is managed by 1Valet, or already holds that code or card.
422 face_rejected: a photo isn't good enough to learn the face from. error.photos lists each refused photo (photo, from 0) and its reason: no_face, many_faces, too_small, unclear or unreadable.
503 face_unavailable: faces can't be learned right now; try again shortly.
DELETE /intercoms/{intercom_id}/entries/{entry_id}

Remove a directory entry

Needs the intercoms:write scope.

Credentials that named it no longer do.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).
entry_id required path integer

Responses

204 Removed.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
409 conflict: the intercom is managed by 1Valet.
PATCH /intercoms/{intercom_id}/entries/{entry_id}

Change a directory entry

Needs the intercoms:write scope.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).
entry_id required path integer

Body

kind "resident" | "concierge" · optional
name string, up to 100 characters · optional
sort integer or null · optional
unit string or null · optional

Responses

200 The entry. · returns a IntercomEntry

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
409 conflict: the intercom is managed by 1Valet.
GET /intercoms/{intercom_id}/concierge

Read an intercom's concierge prompt

Needs the intercoms:read scope.

The intercom's changes to its site's concierge prompt, and the prompt a conversation starts with.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).
language optional query "auto" | "en" | "fr" | "es"

Responses

200 The intercom's prompt changes and the prompt in force.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
PATCH /intercoms/{intercom_id}/concierge

Change an intercom's concierge prompt

Needs the intercoms:write scope.

Fields left out keep their values; an empty string clears one, and the site's applies again.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Body

knowledge string, up to 8000 characters · optional What it should know at this entrance.
knowledge_mode "append" | "replace" · optional append: after the site's knowledge. replace: instead of it.
style string, up to 2000 characters · optional How the concierge speaks at this intercom, in place of the site's.

Responses

200 The intercom's prompt changes and the prompt in force.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
GET /intercoms

List intercoms

Needs the intercoms:read scope.

Intercoms your organization owns, ordered by ID.

Parameters

Name In Type Description
limit optional query integer, 1–100, default 50
starting_after optional query string ID of the last item on the previous page.
site_id optional query string Only intercoms at this site.
q optional query string Only intercoms whose ID or name contains this, ignoring case.

Responses

200 A page of intercoms.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
429 Too many requests. Retry after the Retry-After header.
POST /intercoms

Add an intercom to a site

Needs the intercoms:write scope.

Adds an intercom to one of your sites by the Serial on its label. The intercom must be installed and online. The first organization to add an intercom keeps it. Adding an intercom your organization already has moves it to the given site.

Body

serial string · required The Serial on the intercom's label, 1KIC-XXXX-XXXX-XXXX, in any case, with or without dashes.
site_id string · required
management "1valet" | "1key" · optional How it's managed, fixed once it's added: by the building's 1Valet account, or here.
name string or null · optional

Responses

200 The intercom, now at the site. · returns a Intercom

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
409 conflict: the intercom is managed the other way, or is enrolled with 1Valet and 1key was asked.
422 intercom_not_addable The intercom can't be added. The Serial is unknown or a hub's, the intercom has not come online, or another organization has it.
DELETE /intercoms/{intercom_id}/enrollment

End a 1Key intercom's enrollment

Needs the intercoms:write scope.

The intercom goes back to its code prompt. Its directory, codes and settings stay, for when it enrolls again.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Responses

204 Ended.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
409 conflict: the intercom is managed by 1Valet.
GET /desktop/config

Where the desktop intercom's updates and models are

For the desktop virtual intercom, before it has joined a building: the folder its update feed is in (appcast-macos.xml, appcast-windows.xml and the packages) and the folder its face models are in, each model under the SHA-256 of its bytes. Both are on this API, under /desktop/files. No API key. 404 on a 1Key with no desktop downloads.

Responses

200 The two folders.

Errors

404 not_found No such resource, or it is not your organization's.
GET /desktop/files/{path}

Fetch one of the desktop intercom's files

Redirects (302) to a signed URL for the file, good for an hour. path is the file's path under the feed: appcast-macos.xml, 1Key-Virtual-Intercom-0.3.0-setup.exe, models/<sha256>. No API key. 404 for a file that isn't there.

Parameters

Name In Type Description
path required path string

Responses

302 The signed URL is in Location.

Errors

404 not_found No such resource, or it is not your organization's.
GET /intercoms/{intercom_id}/codes

Read an intercom's codes

Needs the intercoms:read scope.

The building's access codes and guest QR codes, as the cloud last pulled them from the building's 1Valet account and sent them to its intercoms, which check them offline too. Codes are masked: a code longer than 4 characters shows its last two. QR codes and their secrets are never returned. Read-only: they are managed in 1Valet. Empty, with null times, for an intercom that isn't enrolled.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Responses

200 The codes.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
POST /intercoms/{intercom_id}/concierge/sessions

Start a concierge conversation

Needs the intercoms:command scope.

A conversation as the intercom starts one when a visitor wakes its concierge: the gateway to connect to, and a credential for it, valid for connecting for 60 seconds. It counts toward the site's limits and ends a conversation the intercom has open.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Body

language "auto" | "en" | "fr" | "es" · optional

Responses

201 The conversation. · returns a ConciergeStart

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
409 concierge_unavailable: the intercom isn't at a site, or its site's concierge isn't enabled.
429 quota_exceeded: the site has had its conversations for the day, or its minutes for the month.
503 concierge_busy: the site has its most conversations open.
POST /intercoms/{intercom_id}/door/unlock

Open an intercom's door

Needs the intercoms:command scope.

Opens the door now, through the intercom's own relay or the building's access controller, as the building is set up. The unlock expires 10 seconds after it is sent: an intercom that gets it later refuses it (409 unlock_expired), so a delayed one never opens the door late. With an Idempotency-Key, a retry gets the first answer and the intercom opens the door once. Recorded as a door.unlocked event with method remote.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).
Idempotency-Key optional header string, up to 255 characters Any unique string, up to 255 characters. A retry with the same key within 24 hours returns the first response instead of sending the command again.

Responses

200 The door opened.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
409 unlock_expired unlock_expired: the intercom got the unlock after it expired, and the door did not open. Or idempotency_conflict.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The intercom did not answer within 10 seconds. The door may have opened; retry with the same Idempotency-Key.
DELETE /intercoms/{intercom_id}/credentials/{credential_id}

Remove a code or card

Needs the intercoms:write scope.

The intercom stops accepting it.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).
credential_id required path integer

Responses

204 Removed.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
409 conflict: the intercom is managed by 1Valet.
PATCH /intercoms/{intercom_id}/credentials/{credential_id}

Change a code or card

Needs the intercoms:write scope.

Its label, entry, use, schedule or whether it's enabled; not its code.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).
credential_id required path integer

Body

card_format "decimal" | "wiegand26" | "hex" | "hex_reversed" · optional
code string · optional A pin: 4 to 10 digits. A card: decimal, facility:card (Wiegand 26-bit) or a hex UID. Only when adding.
consent boolean · optional A face: the person agreed to their face being used to open this door. Only when adding.
enabled boolean, default true · optional
entry_id integer or null · optional
kind "pin" | "card" | "face" · optional
label string or null · optional
photos array of string · optional A face: JPEGs of the face, 112 to 4,096 pixels on each side, at most 90,000 bytes in all. Only when adding; not stored.
schedule AccessSchedule or null · optional
type "general" | "disposable" · optional

Responses

200 The credential, without its code. · returns a IntercomCredential

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
409 conflict: the intercom is managed by 1Valet.
GET /intercoms/{intercom_id}/settings

Read an intercom's settings

Needs the intercoms:read scope.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Responses

200 The settings. · returns a IntercomSettings

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
PATCH /intercoms/{intercom_id}/settings

Change a 1Key intercom's settings

Needs the intercoms:write scope.

Sent to the intercom as its config.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Body

contact_input integer or null · optional
contact_normally "closed" | "open" | null · optional
held_open_s integer or null · optional Needs a contact.
languages array of string · optional
locale string · optional
management "1valet" | "1key" · optional
pulse_ms integer, 100–60000 · optional
relay_port integer or null · optional
temperature_unit "c" | "f" · optional

Responses

200 The settings. · returns a IntercomSettings

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
409 conflict: the intercom is managed by 1Valet.
GET /intercoms/{intercom_id}/uptime

Get an intercom's uptime

Needs the intercoms:read scope.

When the intercom was connected to the cloud, measured as a hub's (GET /hubs/{hub_id}/uptime): the same ranges, days in its site's time zone.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).
range optional query "24h" | "7d" | "30d" The window. Default 24h.

Responses

200 The intercom's uptime. · returns a Uptime

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
GET /intercoms/{intercom_id}/entries

List an intercom's directory

Needs the intercoms:read scope.

Who visitors find on the intercom, as it holds them, for either management.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Responses

200 The entries.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
POST /intercoms/{intercom_id}/entries

Add a directory entry

Needs the intercoms:write scope.

For an intercom managed in 1Key.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Body

kind "resident" | "concierge" · optional
name string, up to 100 characters · optional
sort integer or null · optional
unit string or null · optional

Responses

200 The entry. · returns a IntercomEntry

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
409 conflict: the intercom is managed by 1Valet.
GET /intercoms/{intercom_id}/directory

Read an intercom's directory

Needs the intercoms:read scope.

The residents and suites of the intercom's building, as the cloud last pulled them from the building's 1Valet account, every 2 minutes. Read-only: they are managed in 1Valet. Empty, with null times, for an intercom that isn't enrolled.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Responses

200 The directory.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
DELETE /intercoms/{intercom_id}

Remove an intercom

Needs the intercoms:write scope.

Removes the intercom from your organization and the cloud: its certificates and its AWS IoT thing are deleted, and so is everything recorded about it (events, sessions, uptime, alarms, connection, its enrollment). The building's 1Valet account is not changed. confirm must repeat the intercom's ID.

The intercom can't reconnect afterwards. Factory reset it and add it again by its Serial (POST /intercoms) once it has requested a new certificate. An intercom.deleted signal goes out on the event streams. Owners and admins only (403 forbidden).

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Body

confirm string · required The intercom's ID.

Responses

204 Removed.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
500 AWS IoT refused part of the removal. The intercom is still in your organization; try again.
GET /intercoms/{intercom_id}

Get an intercom

Needs the intercoms:read scope.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Responses

200 The intercom. · returns a Intercom

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
PATCH /intercoms/{intercom_id}

Update an intercom

Needs the intercoms:write scope.

Renames the intercom, moves it to another of your sites, or both.

Parameters

Name In Type Description
intercom_id required path string The intercom's ID, its Serial (lowercase).

Body

name string or null · optional Display name. null clears it.
site_id string · optional Move the intercom to this site.

Responses

200 The updated intercom. · returns a Intercom

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.