Contacts¶
Warning
The field email was renamed to identifier. For compatibility reasons the email field will still be returned and accepted by the Tapkey Management API. Please switch to the new identifier field as the email field is depracted now and will be removed in a future version.
Previously the field email was used to identify tapkey users only but the identifier field (and email as well) can now be assigned to users of external identity providers as well. For Tapkey users the field ipId will be set to tapkey.
Get List of Contacts¶
Get a list of this owner's contacts.
Scope¶
read:core:entities
Parameters¶
| Name | Type | Location | Description |
|---|---|---|---|
ownerAccountId | string | path | The owner account to get contacts for. |
Success Response¶
200 OK
[
{
"id": "1",
"ownerId": "1",
"comment": "A comment describing this contact.",
"ipId": "tapkey",
"identifier": "user1@tapkey.com",
"title": "User One"
},
{
"id": "2",
"ownerId": "1",
"comment": "A comment describing this contact.",
"ipId": "tapkey",
"identifier": "user2@tapkey.com",
"title": null
}
]
Error Responses¶
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 400 | Generic Error | |
| 401 | Unauthorized | |
| 403 | Forbidden |
Get Contact by ID¶
Get the specified contact.
Scope¶
read:core:entities
Parameters¶
| Name | Type | Location | Description |
|---|---|---|---|
ownerAccountId | string | path | The owner account to get contacts for. |
id | string | path | The contact's ID. |
Success Response¶
200 OK
{
"id": "1",
"ownerId": "1",
"comment": "A comment describing this contact.",
"ipId": "tapkey",
"identifier": "user1@tapkey.com",
"title": "User One"
}
Error Responses¶
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 400 | Generic Error | |
| 401 | Unauthorized | |
| 403 | Forbidden |
Create Contact¶
Creates a new contact under the specified owner account.
Scope¶
write:core:entities
Parameters¶
| Name | Type | Location | Description |
|---|---|---|---|
ownerAccountId | string | path | The owner account to get contacts for. |
Body¶
{
"ipId": "tapkey",
"identifier": "user1@tapkey.com",
"title": "User One",
"comment": "A comment describing this contact."
}
Creates a contact for the given identifier and ipId. For Tapkey-native users use tapkey as the ipId. For uses of other identity providers, use their ipId.
Warning
For legacy reasons, if the ipId is not set, the default tapkey is be used. This might change in future.
or
{
"ipId": "1",
"ipUserId": "1"
}
1. Info
It is not possible to mix these options. Passing both, indentifier and ipUserId will be rejected.
Success Response¶
200 OK
{
"id": "1",
"ownerId": "1",
"comment": "A comment describing this contact.",
"ipId": "tapkey",
"identifier": "user1@tapkey.com",
"title": "User One"
}
or
{
"id": "1",
"ipId": "1",
"ipUserId": "1",
"ownerId": "1",
"identifier": "null"
}
Error Responses¶
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 400 | Generic error | |
| 401 | Unauthorized | |
| 403 | Forbidden | |
| 409 | NothingToDo | A Contact with this data already exists for this owner account |
Patch Contact¶
Patch the specified contact.
The following properties can be patched:
commenttitle
Scope¶
write:core:entities
Parameters¶
| Name | Type | Location | Description |
|---|---|---|---|
ownerAccountId | string | path | The owner account to get contacts for. |
id | string | path | The contact's ID. |
Body¶
{
"comment": "A new comment describing this contact.",
"title": "User New"
}
Success Response¶
200 OK
[
{
"id": "1",
"ownerId": "1",
"comment": "A new comment describing this contact.",
"ipId": "tapkey",
"identifier": "user1@tapkey.com",
"title": "User New"
}
]
Error Responses¶
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 400 | Generic Error | |
| 401 | Unauthorized | |
| 403 | Forbidden | |
| 404 | ContactNotFound | Contact not found |
Delete Contact¶
Delete the specified contact.
Scope¶
write:core:entities
Parameters¶
| Name | Type | Location | Description |
|---|---|---|---|
ownerAccountId | string | path | The owner account to get contacts for. |
id | string | path | The contact's ID. |
Success Response¶
204 OK
Error Responses¶
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 400 | Generic Error | |
| 400 | ContactHasOwnerAccountPermissions | Contact has permissions - remove them before |
| 400 | ContactHasGrants | Contact has grants - remove them before |
| 401 | Unauthorized | |
| 403 | Forbidden | |
| 404 | ContactNotFound | Contact not found |
Get Grants for Contact¶
Get a queryable list of grants assigned to the given contact.
Scope¶
read:grants
Parameters¶
Tip
The returned list can be filtered using OData query parameters.
| Name | Type | Location | Description |
|---|---|---|---|
ownerAccountId | string | path | The owner account to get contacts for. |
id | string | path | The contact's ID. |
Success Response¶
200 OK
[
{
"contact": {
"id": "1",
"ownerId": "1",
"comment": "A new comment describing this contact.",
"ipId": "tapkey",
"identifier": "user1@tapkey.com",
"title": "User One"
},
"boundCard": null,
"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": "Ok",
"active": true,
"boundCardId": null
}
]
Error Responses¶
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 400 | Generic Error | |
| 401 | Unauthorized | |
| 403 | Forbidden |
Revoke Contact's Grants¶
Revoke all grants issued to the given contact.
This operation will initiate the process of revoking all grants issued to a contact (i.e. a smartphone-based grant). All keys issued for the contact's grants will be added to the revocation list (RCL) and the revocation process is started.
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 revocation list will be implicitly revoked too. In this case, keys implicitly revoked as side effects will be renewed automatically as soon as the affected smartphone is online. Thus, users of affected smartphone most likely won’t recognize the renewal process.
A list of grants, for which keys have been issued that are being implicitly revoked as a side effect is returned by this operation. By setting the dryRun parameter 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 contacts for. |
id | string | path | The contact'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. |
Success 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.
Success Response¶
200 OK
[
{
"dryRun": false,
"grantRevoked": {
"contact": {
"id": "1",
"ownerId": "1",
"comment": "A new comment describing this contact.",
"ipId": "tapkey",
"identifier": "user1@tapkey.com",
"title": "User One"
},
"boundCard": null,
"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
}
}
]
Error Responses¶
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 400 | Generic Error | |
| 401 | Unauthorized | |
| 403 | Forbidden | |
| 404 | Not found | Grant not found |
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.