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"
},
]
Grant State¶
For more information about the process of revoking grants, and how a the active
and state
properties reflect the state of a grant's revocation, visit the Revoking Access guide.
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.
A grant containing ICAL time restrictions will be considered valid from the time specified as DTSTART
. If there are multiple VEVENT
instances, the grant is considered valid starting from the earliest DTSTART
. Keys for a grant can be retrieved at the earliest 3 days before the grant is valid.
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
Info
DTSTART
values must either specify a time zone or use UTC. The use of local time (omitting the time zone and not specifying UTC by adding Z
) is not supported.
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
Info
The ICAL will be evaluated on the lock, where memory and computing power are limited. When a grant is created, the Tapkey Trust Service checks whether the affected locks will be able to process the specified ICAL. If that is not the case, the operation returns TimeRestrictionIcalTooComplex
. In general, the complexity of an ICAL restriction is driven by the complexity of the specified time zone and the number of RRULE
s specified. RRULE
s require much more processing power than, e.g., RDATE
s.
Time zones¶
Tapkey has full support for all time zones apart from the exceptions listed below. The VCALENDAR
may only refer to a single time zone. Multiple time zones must not occur within a single VCALENDAR
.
The following time zones are not supported:
- Pacific/Guam
- Asia/Manila
Support for the following time zones is limited:
- America/Campo_Grande
- America/Cuiaba
- America/Sao_Paulo
- Asia/Tehran
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:
timeRestrictionIcal
validBefore
validFrom
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. |
Info
The dryRun
parameter is required. If omitted, the request will fail.
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
}
}
]
Grant State¶
For more information about the process of revoking grants, and how a the active
and state
properties reflect the state of a grant's revocation, visit the Revoking Access guide.
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