Grants

GET/Owners/{ownerAccountId}/Grants

PUT/Owners/{ownerAccountId}/Grants

GET/Owners/{ownerAccountId}/Grants/{id}

PATCH/Owners/{ownerAccountId}/Grants/{id}

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

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

Get List of Grants

GET/Owners/{ownerAccountId}/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

PUT/Owners/{ownerAccountId}/Grants

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

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/Owners/{ownerAccountId}/Grants/{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/Owners/{ownerAccountId}/Grants/{id}

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

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

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

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

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

  1. RFC 5545, section 3.4., iCalendar Object ↩

  2. RFC 5545, section 3.6.1., Event Component ↩