eKey

Represents an eKey on the UniKey CORE Platform

The eKey object

Attributes
Name Type Description
id UUID The eKey’s ID
name String The eKey’s name
type String Type of eKey to send the User
status String The current status of the eKey
valid_from DateTime When the eKey becomes available to use
valid_to DateTime When the eKey becomes inactive
schedule_start String Time limited only Cron format Specifies the time of day the eKey becomes active
schedule_end String Time limited only Cron format Specifies the time of day the eKey becomes inactive
message String Message to accompany the eKey
user_id UUID The ID of the user that the eKey belongs to
lock_id UUID The ID of the lock that the eKey belongs to
eKey Type Definitions
Name Description
owner Owner of the Lock
admin Has administrative privileges on the Lock
anytime Can access the Lock at anytime until their eKey is revoked
scheduled Can access the Lock in the hours specified
guest Has access to the Lock the next 24 hours after the eKey is sent
eKey Status Definitions
Name Description
pending The eKey has not been accepted and can not be used
accepted The eKey has been accepted and can be used
revoked The eKey has been revoked and can not be used
Error Sub-status Definitions
Name Sub-status Description
Payment Required 402 The User has run out of eKeys and needs to buy a new eKey
Unprocessable Entity 422 The User is no longer allowed to send eKeys
Start/End Format

Start and End use a form of Cron expression to determine the correct time. Only min, hour and day of week are currently supported. Other fields must be given an asterisk.

 ┌───────────── min (0 - 59)
 │ ┌────────────── hour (0 - 23)
 │ │ ┌─────────────── *
 │ │ │ ┌──────────────── *
 │ │ │ │ ┌───────────────── day of week (0 - 6) (0 to 6 are Sunday to Saturday)
 │ │ │ │ │ ┌────────────────── *
 │ │ │ │ │ │
 * * * * * *  command to execute
Action Permission Requirements
  Lock Owner Lock Admin Lock Guest
revoke All eKeys Self, Admin, Guest None
grant All Self, Admin, Guest None
rename All Self, Admin, Guest Self
delete All Self, Admin, Guest Self
reschedule All Self, Admin, Guest None
send All All None

API

POST /ekey

Creates a new eKey. The eKey will be given to the owner of email and will have the ability to access the Lock corresponding to lock_id. The eKey must have a designated valid_from and valid_to. These fields determine the lifetime of the eKey. In addition to these two fields, there is also the option of specifying schedule_start and schedule_end (if the eKey type is set to anytime), which designate the time of day the eKey will be active.

Request Properties
Name Type Description
email String Required The email of the User receiving the eKey
lock_id UUID Required The ID of the desired Lock
type String Required Type of eKey to send the User
valid_from DateTime When the eKey becomes available to use
valid_to DateTime When the eKey becomes inactive
schedule_start String Scheduled only Specifies the time of day the eKey becomes active
schedule_end String Scheduled only Specifies the time of day the eKey becomes inactive
message String Message to accompany the eKey
Response Properties

Returns the new eKey object

Example Request

Example 1 Sending an owner eKey to johnsmith@unikey.com

POST /ekey

{
    "email": "johnsmith@unikey.com",
    "lock_id": "65f1daa2-1a4e-488a-ad46-07a375bc743c",
    "type": "anytime",
    "message": "Here's your eKey."
}

Example 2 Sending a scheduled eKey to johnsmith@unikey.com, specifying that it can only be used between the hours of 3 and 4 PM (schedule_start and schedule_end) that is usable from 8/16/2016 1:13:02 PM to 8/28/2016 1:13:14 PM (valid_from and valid_to)

POST /ekey

{
    "email": "johnsmith@unikey.com",
    "lock_id": "65f1daa2-1a4e-488a-ad46-07a375bc743c",
    "type": "scheduled",
    "message": "Here's your eKey.",
    "valid_from": "8/16/2016 1:13:02 PM",
    "valid_to": "8/28/2016 1:13:14 PM",
    "schedule_start": "* 15 * * * *",
    "schedule_end": "* 16 * * * *"
}

Example 3 Sending a guest eKey to johnsmith@unikey.com, giving the User 24 hours to access the Lock

POST /ekey

{
    "email": "johnsmith@unikey.com",
    "lock_id": "65f1daa2-1a4e-488a-ad46-07a375bc743c",
    "type": "guest",
    "message": "Here's your eKey."
}
Example Response
HTTP/1.1 201 Created

Example 1

{
    "id": "c23a1bd9-e512-49b1-9855-882d43a71873",
    "name": "eKey Name",
    "status": "accepted",
    "type": "owner",
    "message": "Here's your eKey.",
    "valid_from": "8/16/2016 1:13:02 PM",
    "valid_to": "8/28/2016 1:13:14 PM",
    "schedule_start": "* * * * * *",
    "schedule_end": "* * * * * *",
    "user_id": "cb58a46d-f433-422f-8e64-043f103a5715",
    "lock_id": "65f1daa2-1a4e-488a-ad46-07a375bc743c"
}

Example 2

{
    "id": "c23a1bd9-e512-49b1-9855-882d43a71873",
    "name": "eKey Name",
    "status": "accepted",
    "type": "scheduled",
    "message": "Here's your eKey.",
    "valid_from": "8/16/2016 1:13:02 PM",
    "valid_to": "8/28/2016 1:13:14 PM",
    "schedule_start": "* 15 * * * *",
    "schedule_end": "* 16 * * * *",
    "user_id": "cb58a46d-f433-422f-8e64-043f103a5715",
    "lock_id": "65f1daa2-1a4e-488a-ad46-07a375bc743c"
}

Example 3

{
    "id": "c23a1bd9-e512-49b1-9855-882d43a71873",
    "name": "eKey Name",
    "status": "accepted",
    "type": "guest",
    "message": "Here's your eKey.",
    "valid_from": "8/16/2016 1:13:02 PM",
    "valid_to": "8/17/2016 1:13:14 PM",
    "schedule_start": null,
    "schedule_end": null,
    "user_id": "cb58a46d-f433-422f-8e64-043f103a5715",
    "lock_id": "65f1daa2-1a4e-488a-ad46-07a375bc743c"
}
PUT /ekey/{ekey_id}

Updates an eKey

Request Properties
Name Type Description
ekey_id UUID Required The ID of the eKey you want to update
Response Properties

Returns the updated eKey object

Example Request

This shows how to update an eKey that has the ID 4e269466-e6b1-4e34-8e0e-d74f3fd65688. Note: Ensure that the ekey_id is NOT present in the JSON request body. Its presence will be ignored by the server.

PUT /ekey/4e269466-e6b1-4e34-8e0e-d74f3fd65688

{
    "name": "test eKey",
    "type": "guest",
    "message": "Here's your eKey.",
    "valid_from": "8/16/2016 1:13:02 PM",
    "valid_to": "8/28/2016 1:13:14 PM",
    "schedule_start": "0 15 * * * *",
    "schedule_end": "0 16 * * * *"
}
Example Response
HTTP/1.1 200 OK

{
    "id": "4e269466-e6b1-4e34-8e0e-d74f3fd65688",
    "name": "eKey Name",
    "type": "guest",
    "status": "accepted",
    "message": "Here's your eKey.",
    "valid_from": "8/16/2016 1:13:02 PM",
    "valid_to": "8/28/2016 1:13:14 PM",
    "schedule_start": "0 15 * * * *",
    "schedule_end": "0 16 * * * *",
    "user_id": "cb58a46d-f433-422f-8e64-043f103a5715",
    "lock_id": "65f1daa2-1a4e-488a-ad46-07a375bc743c"
}
GET /ekey/{ekey_id}

Returns information about a given eKey

Request Properties
Name Type Description
ekey_id UUID Required The ID of the desired eKey
Response Properties

Returns an eKey object

Example Request

This shows how to obtain an eKey that has the ID 4e269466-e6b1-4e34-8e0e-d74f3fd65688.

GET /ekey/4e269466-e6b1-4e34-8e0e-d74f3fd65688/
Example Response
HTTP/1.1 200 OK

{
    "id": "4e269466-e6b1-4e34-8e0e-d74f3fd65688",
    "name": "eKey Name",
    "type": "guest",
    "status": "accepted",
    "message": "Here's your eKey.",
    "valid_from": "8/16/2016 1:13:02 PM",
    "valid_to": "8/28/2016 1:13:14 PM",
    "schedule_start": "0 15 * * * *",
    "schedule_end": "0 16 * * * *",
    "user_id": "cb58a46d-f433-422f-8e64-043f103a5715",
    "lock_id": "65f1daa2-1a4e-488a-ad46-07a375bc743c"
}
GET /locks/{lock_id}/ekeys

Returns all eKeys for a given Lock

Request Properties
Name Type Description
lock_id UUID Required The ID of the desired Lock
Response Properties

Returns an array of eKey objects

Example Request

This example shows how to obtain all of the eKeys for the Lock with an ID of 65f1daa2-1a4e-488a-ad46-07a375bc743c.

GET /locks/65f1daa2-1a4e-488a-ad46-07a375bc743c/ekeys
Example Response
HTTP/1.1 200 OK

{
  "ekeys": [
    {
      "id": "1034ef96-e8ea-4916-bdc8-272a253c8c92",
      "name": "eKey Name",
      "type": "guest",
      "status": "accepted",
      "message": "Here's your eKey.",
      "valid_from": "8/16/2016 1:13:02 PM",
      "valid_to": "8/28/2016 1:13:14 PM",
      "schedule_start": "0 15 * * * *",
      "schedule_end": "0 16 * * * *",
      "user_id": "cb58a46d-f433-422f-8e64-043f103a5715",
      "lock_id": "65f1daa2-1a4e-488a-ad46-07a375bc743c"
    },
    {
      "id": "fc80cc85-f95d-4c64-8695-648569d0a1df",
      "name": "eKey Name",
      "type": "guest",
      "status": "accepted",
      "message": "Here's your eKey.",
      "valid_from": "8/16/2016 1:13:02 PM",
      "valid_to": "8/28/2016 1:13:14 PM",
      "schedule_start": "0 15 * * * *",
      "schedule_end": "0 16 * * * *",
      "user_id": "cb58a46d-f433-422f-8e64-043f103a5715",
      "lock_id": "65f1daa2-1a4e-488a-ad46-07a375bc743c"
    },
  ]
}
DELETE /ekey/{ekey_id}

Revokes the privlidges of a given eKey

Request Properties
Name Type Description
ekey_id UUID Required The ID of the desired eKey
Response Properties

Returns the revoked eKey object

Example Request

This example shows how to revoke an eKey with the ID of f523a788-97ed-4594-8395-7b1cd5bfaa8b.

DELETE /ekey/f523a788-97ed-4594-8395-7b1cd5bfaa8b
Example Response
HTTP/1.1 200 OK

{
    "id": "f523a788-97ed-4594-8395-7b1cd5bfaa8b",
    "name": "eKey Name",
    "status": "pending",
    "type": "guest",
    "message": "Here's your eKey.",
    "valid_from": "8/16/2016 1:13:02 PM",
    "valid_to": "8/17/2016 1:13:14 PM",
    "schedule_start": "* * * * * *",
    "schedule_end": "* * * * * *",
    "user_id": "cb58a46d-f433-422f-8e64-043f103a5715",
    "lock_id": "65f1daa2-1a4e-488a-ad46-07a375bc743c"
}