Entities¶

Overview¶

This page outlines the entity-relationship model of the Tapkey Access Management Web 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 : ""
          Grant-Template |o--o{ Grant : "is based on"
          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.

Entities used in the Access 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.

Grant Template¶

A grant template to be used as access permission for a grantee. The grant template defines the time restriction in the same way as the grant itself but can be reused across multiple grants. Changing the time restriction of the grant template will update all the access permissions that use it.

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.

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.