Skip to content

Entities

Overview

This page outlines the entity-relationship model of the Tapkey Management API. Descriptions of the entities can be found in the respective sections below the diagram.

Entity-Relationship Diagram

erDiagram Contact }o--o{ Owner-Account : "is co-admin" Contact ||--o{ Owner-Account : "owns" Contact }o--|| Owner-Account : "" Bound-Card }o--|| Owner-Account : "" Bound-Lock }o--|| Owner-Account : "" Contact }o--|| User : "maps" Contact |o--o{ Grant : "" Bound-Card |o--o{ Grant : "" Bound-Lock |o--o{ Grant : "" Lock-Group |o--o{ Grant : "" Physical-Lock ||--|{ Bound-Lock : "" Physical-Card ||--o{ Bound-Card : "" Lock-Group }o--o{ Bound-Lock : "is member of" Lock-Group }o--|| Owner-Account : "belongs to"

Basics

Entity IDs

All entities are identified by their entity IDs. While most IDs seem to be constructed from GUIDs, which by their nature aren't case-sensitive, this isn't the case always and can change at any time. E.g. IDs of physical locks are constructed from Base-64 encoded strings, which by their nature are case-sensitive. It's therefore required to treat all IDs as case-sensitive.

Warning

Entity IDs must always be treated case-sensitive.

Entities used in the Management API

Owner Account

A lock or card (NFC transponder) is owned by an owner account which in turn is owned by a user, the owner.

Contact

A relation between a user and an owner. Represents the owner's view of a related user. E.g. a grant is always assigned to a contact instead of a user.

Bound Lock

An owner's view of a lock. If a lock is registered (bound) by an owner, a bound lock instance is created, which the lock owner can manage grants for. No more than one bound lock is marked active for a given physical lock at any single point in time.

Lock Group

A group of locks. Acts similar to a bound lock. After a lock is added to or removed from a group, it needs to be synchronized in order to update the respective group information on the lock.

Bound Card

An owner's view of an access media (card). When a card is registered (bound) by an owner account, an instance of bound card is created. No more than one instance of bound card is marked active for a given physical card at any single point in time.

Grant

An access permission for a contact or a bound card to a bound lock.

Other entities

User

Represents a user who can sign in to Tapkey.

Physical Lock

The representation of a physical lock. As a lock could potentially be owned by multiple people over time, each having a separate view on it, there's no direct relationship between physical locks and owner accounts.

Info

IDs of physical locks must be considered case-sensitive.

Physical Card

The representation of a physical access media. Like locks, cards can be owned by multiple owner accounts over time. So there's no direct relationship between physical cards and owner accounts.