Skip to content

Cards

Get list of cards

GET/Owners/{ownerAccountId}/BoundCards

Get a list of this owner's cards.

Scope

read:core:entities

Parameters

Name Type Location Description
ownerAccountId string path The owner account's ID.

Response

Info

The property label may contain information that is printed on the actual card while title is the card's title as chosen by the user.

200 OK
[
  {
    "id": "1",
    "label": "",
    "uid": "AHHCCh07gB==",
    "isActive": true,
    "physicalCardId": "1",
    "ownerAccountId": "1",
    "bindDate": "2018-12-12T12:30:00.000Z",
    "unbindDate": null,
    "title": "User One's Card",
    "nofGrantsCapacity": 12
  }
]

Get card by ID

GET/Owners/{ownerAccountId}/BoundCards/{id}

Get the specified card.

Scope

read:core:entities

Parameters

Name Type Location Description
ownerAccountId string path The owner account's ID.
id string path The card's ID.

Response

Info

The property label may contain information that is printed on the actual card while title is the card's title as chosen by the user.

200 OK
{
  "id": "1",
  "label": "",
  "uid": "AHHCCh07gB==",
  "isActive": true,
  "physicalCardId": "1",
  "ownerAccountId": "1",
  "bindDate": "2018-12-12T12:30:00.000Z",
  "unbindDate": null,
  "title": "User One's Card",
  "nofGrantsCapacity": 12
}

Patch card

PATCH/Owners/{ownerAccountId}/BoundCards/{id}

Patch the details of a Bound Card.

The following properties can be patched using this operation:

  • title

Scope

write:core:entities

Parameters

Name Type Location Description
ownerAccountId string path The owner account's ID.
id string path The card's ID.

Response

Info

The property label may contain information that is printed on the actual card while title is the card's title as chosen by the user.

204 No Content

Get grants for card

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

Get a queryable list of Grants for the given card.

Scope

read:grants

Parameters

Info

The returned list can be filtered using OData query parameters.

Name Type Location Description
ownerAccountId string path The owner account's ID.
id string path The card's ID.

Response

200 OK
[
  {
    "contact": null,
    "boundCard": {
      "id": "1",
      "label": "",
      "uid": "AHHCCh07gB==",
      "isActive": true,
      "physicalCardId": null,
      "ownerAccountId": "1",
      "bindDate": "2018-12-12T12:30:00.000Z",
      "unbindDate": null,
      "title": "User One's Card",
      "description": null,
      "nofGrantsCapacity": null
    },
    "boundLock": {
      "lockType": {
        "id": "TK.Td30",
        "manufacturerId": 1,
        "modelName": "Td30",
        "supportedTechnologies": [
          "nfc",
          "ble"
        ]
      },
      "supportedFeatures": {
        "timeRestrictionIcalSupport": "Supported"
      },
      "healthStatuses": null,
      "id": "1",
      "physicalLockId": "AAChsgq2",
      "lockTypeId": "TK.Td30",
      "ownerAccountId": "1",
      "bindDate": "2018-12-12T12:00:00.000Z",
      "unbindDate": null,
      "title": "Entrance Door",
      "description": "A description for this lock.",
      "rclSerialNo": 3,
      "rclDate": "2018-12-24T12:00:00.000Z"
    },
    "id": "1",
    "boundLockId": "1",
    "contactId": null,
    "validFrom": null,
    "validBefore": null,
    "timeRestrictionIcal": null,
    "state": "Ok",
    "active": true,
    "boundCardId": "1"
  }
]

Revoke card's grants

POST/Owners/{ownerAccountId}/BoundCards/{id}/RevokeGrants

Revoke all Grants of an absent card that was lost or stolen.

This operation will initiate the revocation process of revoking all Grants that were issued for a card in case the card is not present (i.e. was lost or stolen). In this situation, the key written to the card for the given Grant cannot be deleted from the card directly. Therefore, the alternate process of revoking via the revocation list (RCL) is started.

As the revocation list has a limited capacity, revoking too many card keys for an individual lock can cause the revocation list capacity to be exceeded. In this case, card keys issued before the oldest revoked key contained in the RCL will be implicitly revoked too. The same behavior applies when revoking smartphone-based Grants and respective keys, but in contrast to these, keys written to cards cannot be renewed without manual user interaction. This is why the revocation of card Grants should be carried out with special care.

If a card Grant was revoked this way and therefore the respective key was added to the RCL but the affected card is synchronized afterward, the key will be deleted from the card and removed from the RCL.

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 up front.

Scope

write:grants

Parameters

Name Type Location Description
ownerAccountId string path The owner account's ID.
id string path The card'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": []
    }
}
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": null,
      "boundCard": {
        "id": "1",
        "label": "",
        "uid": "AHHCCh07gB==",
        "isActive": true,
        "physicalCardId": "1",
        "ownerAccountId": "1",
        "bindDate": "2018-12-12T12:30:00.000Z",
        "unbindDate": null,
        "title": "User One's Card",
        "nofGrantsCapacity": 12
      },
      "boundLock": {
        "lockType": {
          "id": "TK.Td30",
          "manufacturerId": 1,
          "modelName": "Td30",
          "supportedTechnologies": [
            "nfc",
            "ble"
          ]
        },
        "supportedFeatures": {
          "timeRestrictionIcalSupport": "Supported"
        },
        "id": "1",
        "physicalLockId": "AAChsgq2",
        "lockTypeId": "TK.Td30",
        "ownerAccountId": "1",
        "bindDate": "2018-12-12T12:00:00.000Z",
        "title": "Entrance Door",
        "description": null,
        "rclSerialNo": 1,
        "rclDate": "2018-12-12T12:00:01.000Z"
      },
      "id": "1",
      "boundLockId": "1",
      "contactId": "1",
      "validFrom": null,
      "validBefore": null,
      "timeRestrictionIcal": null,
      "state": "RevocationPending",
      "active": false,
      "boundCardId": null
    },
    "grantsAffectedAsSideEffect": [],
    "rclState": {
      "rclClassStates": null
    }
  }
]