Revoking Access¶

Concepts¶

Every Tapkey lock holds a list of revoked keys, called revocation list (RCL). Whenever a still valid grant is revoked, the affected lock's revocation list will be updated with the relevant information. The revocation list will be updated whenever a lock is synchronized. Additionally, whenever possible, the updated revocation list will automatically be sent to smartphones holding a valid key for the affected lock. Those smartphones will push the update onto the lock on their next trigger lock attempt.

Keys on NFC Transponders can alternatively be deleted without triggering a revocation process, as the key cannot leave the card and can therefore be safely deleted.

Revoking Grants¶

Grants can be revoked using one of the Tapkey Access Management Web API's revoke operations:

These operations will initiate the process of revoking the specified grants. All keys issued for the grants in question will be added to the respective revocation lists and the revocation process is started.

Alternative to Revoking Card-Based Grants¶

If a grant is related to a card (as opposed to a contact), and the card is still present (i.e. hasn't been lost or stolen), the grant and associated key should get deleted via the

POST/Owners/{ownerAccountId}/Grants/{id}/DeleteFromCard

operation and subsequent card synchronisation instead. This is beneficial compared to a revocation process, because it takes effect immediately and isn't subject to side-effects as outlined in the following.

Side-Effects of Revocation¶

As the revocation list has limited capacity, revoking too many keys for an individual lock can cause the revocation list capacity to be exceeded. In this case, keys issued before the oldest revoked key contained in the revocation list will be implicitly revoked too. If this happens, keys implicitly revoked as side effects will be renewed automatically if they have been issued to mobile devices (as opposed to cards) as soon as the affected device is online. Thus, users of affected smartphones most likely won't recognize the renewal process while affected cards must be synchronised with the server to get affected key renewed.

States of Revoked Grants¶

A grant can be in one of the following states:

State	Description
`Ok`	The grant is valid.
`Expired`	The grant expired (`validBefore` is ⩽ now).
`Revoked`	The grant has been revoked successfully. This only applies to card-based grants that have been deleted via the DeleteFromCard operation. All other grants will remain in the `RevocationPending` state.
`RevocationPending`	The grant has been marked for revocation and the revocation process has started.
`CardDeletionPending`	The card-based grant was marked for deletion and will be deleted the next time the corresponding card is synchronized. No revocation was started via the revocation-control list mechanism.

Note that the grant's active property will be false for any other state than Ok.

The diagram below outlines a grant's state property during the different revocation processes.


graph TD
    subgraph Mobile Keys
        A[Ok] -->|Revoke contact-based grant| B[RevocationPending]
        B -->|Synchronize affected locks| C[RevocationPending]
        B -->|Update RCL during trigger lock| C[RevocationPending]
    end
    subgraph Card-based Keys
        D[Ok] -->|Delete card-based grant| E[CardDeletionPending]
        E -->|Synchronize affected card| F[Revoked]
    end