Grants¶

Get List of Grants¶

Get a list of grants.

Scope¶

read:grants

Parameters¶

Success 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
  },
  {
    "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"
  },
]

Error Responses¶

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.

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¶

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 object¹ 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 events². Events can hold recurrence rules as specified in RFC 5545, section 3.8.5.3..

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 1^st 2020 until January 1^st 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 10^th 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 24^th and December 31^st.

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

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¶

Body¶

{
  "boundLockId": "1",
  "contactId": "1",
  "boundCardId": null,
  "validFrom": null,
  "validBefore": null,
  "timeRestrictionIcal": null
}

Success Response¶

200 OK

{
  "id": "1",
  "boundLockId": "1",
  "contactId": "1",
  "validFrom": null,
  "validBefore": null,
  "timeRestrictionIcal": null,
  "state": "Ok",
  "active": true,
  "boundCardId": null
}

Error Responses¶

Get Grant by ID¶

Get the specified grant.

Scope¶

read:grants

Parameters¶

Success 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
}

Error Responses¶

Patch Grant¶

Patch the specified grant.

The following properties can be patched:

• timeRestrictionIcal
• validBefore
• validFrom

Scope¶

write:grants

Parameters¶

Body¶

{
  "validFrom": "2019-02-01T10:00:00.000Z",
  "validBefore": "2019-03-01T19:00:00.000Z",
  "timeRestrictionIcal": null
}

Success Response¶

204 OK

Error Responses¶

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¶

Success Response¶

The operation returns an array of objects of the following type:

{
    "dryRun": false,
    "grantRevoked": {...},
    "grantsAffectedAsSideEffect": [],
    "rclState": {
      "rclClassStates": null
    }
}

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
    }
  }
]

Error Responses¶

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¶

Success Response¶

204 OK

Error Responses¶