Grants
Get list of grants¶
Get a list of grants.
Scope¶
read:grants
Parameters¶
| Name | Type | Location | Description |
|---|---|---|---|
ownerAccountId |
string | path | The owner account to get grants for. |
Response¶
Info
The exemplary response below shows two types of grants. The first one is a grant assigned to a contact, while the second one is a grant that was issued for a bound card.
200 OK
[ { "contact": { … }, "boundCard": null, "boundLock": { … }, "owner": null, "id": "1", "boundLockId": "1", "contactId": "1", "validFrom": null, "validBefore": null, "timeRestrictionIcal": null, "state": "Ok", "active": true, "boundCardId": null }, { "contact": null, "boundCard": { … }, "boundLock": { … }, "owner": null, "id": "2", "boundLockId": "1", "contactId": null, "validFrom": "2019-02-01T10:00:00.000Z", "validBefore": "2019-03-01T19:00:00.000Z", "timeRestrictionIcal": null, "state": "Revoked", "active": false, "boundCardId": "1" }, ]
Create grant¶
Create a new grant either for a contact or a card.
After a grant was created, the following happens:
- If the grant is issued for a card, the card is marked for synchronisation. The according key is written to the affected card the next time it is synchronised.
The following two scenarios are only applicable if the user is using either the Tapkey app or a third-party app that integrates the Tapkey Mobile SDK in way that it is ready to handle keys for the user:
- If the grant is issued to a user who is not signed in to Tapkey on any compatible device, the grant is just stored and will be sent to the affected user's device, as soon as they log in.
- If the grant is issued to a user who is signed in to Tapkey on a compatible device, according keys will be pushed to the devices, the user is signed in to, as soon as these devices are online.
Restricting grants¶
Grants can have restricted validity. Tapkey offers multiple ways of granting restricted access which are outlined below.
Warning
Make sure to either use validFrom/validBefore or
timeRestrictionIcal. Tapkey will refuse to create grants with both.
Valid from-before¶
The grant's validFrom and validBefore properties can be used to realise
restricted access. If validFrom is set, the grant will be not be valid before
validFrom. If validFrom is null, the grant will be valid immediately. If
validBefore is set, the grant will be valid only before validBefore. If
validBefore is null, the grant will always be valid in the future. If both
validFrom and validBefore are null, the grant is not restricted in any
way.
Examples¶
{ "validFrom": "2019-02-01T10:00:00.000Z", "validBefore": "2019-03-01T19:00:00.000Z", "timeRestrictionIcal": null }
{ "validFrom": null, "validBefore": "2030-03-01T19:00:00.000Z", "timeRestrictionIcal": null }
{ "validFrom": "2020-01-01T10:00:00.000Z", "validBefore": null, "timeRestrictionIcal": null }
Complex ICAL-based restrictions¶
Tip
Make sure to familiarise yourself with RFC 5545, in particular with section 3.6.1. to learn about ICAL events and how they are structured.
The grant's timeRestrictionIcal property can be used to realise complex
access scenarios like, for instance, access windows that recur on a weekly
base.
timeRestrictionIcal must be a string containing an ICAL calendar
object1 with the following skeleton:
BEGIN:VCALENDAR VERSION:2.0 PRODID:https://www.example.com/grants/ END:VCALENDAR
Make sure to choose a unique calendar PRODID for your application, e.g. your
organization's domain.
The calendar passed to Tapkey can contain one or multiple events2. Events can hold recurrence rules as specified in RFC 5545, section 3.8.5.3..
Warning
Make sure that DTSTART matches the first occurrence of the recurring
event and that your calendar does not include references to multiple
time zones. Tapkey will not accept events that do not comply.
Examples¶
{ "validFrom": null, "validBefore": null, "timeRestrictionIcal": "[ one of the ICAL calendars below ]" }
This example allows access every Monday, Tuesday, Wednesday, Thursday and Friday from 10 AM to 6 PM in Berlin time zone starting from January 1st 2020 until January 1st 2021.
BEGIN:VCALENDAR VERSION:2.0 PRODID:https://www.example.com/grants/ BEGIN:VEVENT UID:20190306T155223Z-3998d53f-6f70-4471-af69-a1e91a9ab77a@tapkey.com DTSTAMP:20190306T152941Z DTSTART;TZID=Europe/Berlin:20200101T100000 DTEND;TZID=Europe/Berlin:20200101T180000 RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;UNTIL=20211231T225959Z END:VEVENT END:VCALENDAR
This example allows access from 12 pm to 2 pm in Berlin time zone every Sunday, with the first occurrence on March 10th 2019.
BEGIN:VCALENDAR VERSION:2.0 PRODID:https://www.example.com/grants/ BEGIN:VEVENT UID:20190306T155223Z-3998d53f-6f70-4471-af69-a1e91a9ab77a@tapkey.com DTSTAMP:20190306T155223Z DTSTART;TZID=Europe/Berlin:20190310T120000 DTEND;TZID=Europe/Berlin:20190310T140000 RRULE:FREQ=WEEKLY;BYDAY=SU END:VEVENT END:VCALENDAR
This example allows access every weekday from 8 am to 6 pm in London time zone in 2019 except December 24th and December 31st.
BEGIN:VCALENDAR VERSION:2.0 PRODID:https://www.example.com/grants/ BEGIN:VEVENT UID:20190306T155223Z-3998d53f-6f70-4471-af69-a1e91a9ab77a@tapkey.com DTSTAMP:20190306T155223Z DTSTART;TZID=Europe/London:20190101T080000 DTEND;TZID=Europe/London:20190101T180000 RRULE:FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR;UNTIL=20191231T230000Z EXDATE;TZID=Europe/London:20191224T080000 EXDATE;TZID=Europe/London:20191231T080000 END:VEVENT END:VCALENDAR
Scope¶
write:grants
Parameters¶
| Name | Type | Location | Description |
|---|---|---|---|
ownerAccountId |
string | path | The owner account to create grants for. |
Body¶
{ "boundLockId": "1", "contactId": "1", "boundCardId": null, "validFrom": null, "validBefore": null, "timeRestrictionIcal": null }
Response¶
200 OK
{ "id": "1", "boundLockId": "1", "contactId": "1", "validFrom": null, "validBefore": null, "timeRestrictionIcal": null, "state": "Ok", "active": true, "boundCardId": null }
Get grant by ID¶
Get the specified grant.
Scope¶
read:grants
Parameters¶
| Name | Type | Location | Description |
|---|---|---|---|
ownerAccountId |
string | path | The owner account to get grants for. |
id |
string | path | The grant's ID. |
Response¶
200 OK
{ "contact": { … }, "boundCard": null, "boundLock": { … }, "owner": null, "id": "1", "boundLockId": "1", "contactId": "1", "validFrom": null, "validBefore": null, "timeRestrictionIcal": null, "state": "Ok", "active": true, "boundCardId": null }
Patch grant¶
Patch the specified grant.
The following properties can be patched:
timeRestrictionIcalvalidBeforevalidFrom
Scope¶
write:grants
Parameters¶
| Name | Type | Location | Description |
|---|---|---|---|
ownerAccountId |
string | path | The owner account to patch grants for. |
id |
string | path | The grant's ID. |
Body¶
{ "validFrom": "2019-02-01T10:00:00.000Z", "validBefore": "2019-03-01T19:00:00.000Z", "timeRestrictionIcal": null }
Response¶
204 OK
Revoke grant¶
Start the revocation process for a specific grant.
This operation will initiate the process of revoking a specific grant. The grant can be issued for a card or for a contact. All keys issued for the given grant will be added to the revocation list and the revocation process is started.
If the grant is related to a card (as opposed to a contact), and the card is
still present, the grant and associated key should get deleted via the
DeleteFromCard operation and subsequent card
synchronisation instead. This avoids adding the key to the revocation list and
therefore potential side effects.
As the revocation list has a 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 RCL will be implicitly revoked too. In this case, 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.
A list of grants, for which keys have been issued that are being implicitly
revoked as a side effect is returned by this operation. If setting the dryRun
flag to true, the effect can be queried from the server without actually
executing the revocation. This way, the user can be informed about side effects
upfront.
Scope¶
write:grants
Parameters¶
| Name | Type | Location | Description |
|---|---|---|---|
ownerAccountId |
string | path | The owner account to get grants for. |
id |
string | path | The grant's ID. |
dryRun |
boolean | query | If true, this operation will not actually execute the revocation but only return information about the potential effect. This can be used to inform the user about potential side effects a revocation could have. |
Response¶
The operation returns an array of objects of the following type:
{ "dryRun": false, "grantRevoked": {...}, "grantsAffectedAsSideEffect": [], "rclState": { "rclClassStates": null } }
grantRevoked contains the grant and grantsAffectedAsSideEffect holds a list of grants that have been revoked implicitly as a side effect.
The rclClassStates array contains the updated information of the revocation lists after the revocation process has started, such as: the current size of the list or the maximum number of entries it can hold.
Exemplary Response¶
200 OK
[ { "dryRun": false, "grantRevoked": { "contact": { … }, "boundCard": null, "boundLock": { … }, "id": "1", "boundLockId": "1", "contactId": "1", "validFrom": null, "validBefore": null, "timeRestrictionIcal": null, "state": "RevocationPending", "active": false, "boundCardId": null }, "grantsAffectedAsSideEffect": [], "rclState": { "rclClassStates": null } } ]
Delete grant from card¶
Mark a grant for deletion that was issued to a card that is still present.
Use this operation to revoke a grant that was issued to a card and delete the associated key, if the card is still present (i.e. hasn't been lost or stolen). In this case, the according key won't be added to the revocation list and therefore the risk of other grants being revoked as side effects is avoided.
This operation marks the specified key for deletion. The key will be deleted when the affected card is synchronised the next time. Calling this operation will therefore have no effect until the affected card was synchronised.
To revoke grants from cards that have been lost, use the
Revoke operation instead.
Scope¶
write:grants
Parameters¶
| Name | Type | Location | Description |
|---|---|---|---|
ownerAccountId |
string | path | The owner account to get grants for. |
id |
string | path | The grant's ID. |
Response¶
204 OK