Learn

Hierarchy

You own Products
Each Product contains Subscriptions.
Each Subscription represents a client, customer or device that contains Keys.
Each Key issued has a serial code.
Simple!

In the case of a physical product one can think of a subscription as a consumer that has a warranty period tracked through a serial code. QR Codes can be printed and attached to these physical goods removing the need for receipt-checking. In a software case think of a subscriber as the end user that is issued a Product Key with a validity period, an example would be a Netflix 1-month trial or a Windows 10 Software Box. In an IoT case, it can be both!

The Basics

Step 1

Create an Account here or login with your favourite Social service.

Step 2

After login, hit "Create New" to Create Your First Product. It is recommended (but not required) that you enter the name of your product. Your API Key will then be revealed.

Step 3

Hit 'Add Subscription' to create any subscribers you may have for your Product.

You have the following options as to how these Subscriptions will be treated when they expire:

  • Renew : Subscription gets a fresh new key
  • Extend : Creates a new copy of the key
  • Disable : Changes 'Current' state of key
  • Delete : Key is deleted altogether

Step 4

We do :)

Api Documentation

You have complete access to both Subscriptions and Products i.e List, Create, Read, Update & Delete.
As a graspable concept think of it as no more than a UUID / Guid that has a "life span" after which some "action" must occur! To that end at it's most primitive level it case be even used for something as trivial as generating one-time tokens / vouchers.
We'd much prefer if it be used for something cooler like 'calling back' a low-powered microcontroller with no RTC facility.

Protocol

By default HTTPS is required at all times.
HTTP can only be used by setting the query parameter 'default' to 'false' :

eg. 'http://keyserv.solutions/v1/ProductsApi?default=false'

Operation Verb
List POST | *GET
Create POST
Read POST | *GET
Update PUT / PATCH
Delete DELETE

*For security reasons we have disabled GET requests for the Products & Subscriptions APIs, THIS IS INTENTIONAL. We recommend it only be used on the Keys API which was designed for lighter client-side requests.

IP Address Rate Limitng is also in effect to mitigate any attacks.

Controllers

Products https://keyserv.solutions/v1/ProductsApi
Subscriptions https://keyserv.solutions/v1/SubscriptionsApi
Keys https://keyserv.solutions/v1/KeysApi

Products

Endpoint Spec & Example Returns

List

ProductsApi/Find
Field Type Description Constraint Object
key string API Key Required UUID
POST /v1/ProductsApi/Find HTTP/1.1
Host: keyserv.solutions
Content-Type: application/json; charset=utf-8

{
    "key": "7ecaa17b-8afb-423d-a7fc-861147ecd5f4"
}

Products
[
    {
        "name": "Lawn Trimmer",
        "serial": "944514ef-9263-4978-905a-7028bd0f9e6a",
        "created": "2019-01-13T14:22:00.5404817+02:00"
        "custom": {
            "manufacturerNo": "D2-D1RFS-1",
            "sellOnline": false
        }
    },
    {
        "name": "Bowl",
        "serial": "09b07fd4-d873-49bb-8aa7-e2ec9f463dac",
        "created": "2019-01-13T18:47:01.3575795+02:00"
    }
]

Create

ProductsApi/Save
Field Type Description Constraint Object
key string API Key Required UUID
name string Product Name Optional
custom json Your Own JSON Optional
POST /v1/ProductsApi/Save HTTP/1.1
Host: keyserv.solutions
Content-Type: application/json; charset=utf-8

{
    "name": "Lawn Trimmer",
    "key": "7ecaa17b-8afb-423d-a7fc-861147ecd5f4",
    "custom": {
        "manufacturerNo": "D2-D1RFS-1",
        "sellOnline": false
    }
}

201 : Product
{
        "name": "Lawn Trimmer",
        "serial": "944514ef-9263-4978-905a-7028bd0f9e6a",
        "created": "2019-01-13T14:22:00.5404817+02:00",
        "custom": {
            "manufacturerNo": "D2-D1RFS-1",
            "sellOnline": false
    }
}

Read

ProductsApi/Find
Field Type Description Constraint Object
key string API Key Required UUID
serial string Product Serial Required UUID
POST /v1/ProductsApi/Find HTTP/1.1
Host: keyserv.solutions
Content-Type: application/json; charset=utf-8

{
    "key": "7ecaa17b-8afb-423d-a7fc-861147ecd5f4",
    "serial": "944514ef-9263-4978-905a-7028bd0f9e6a"
}

Product & Subscriptions
{
    "name": "Lawn Trimmer",
    "serial": "944514ef-9263-4978-905a-7028bd0f9e6a",
    "created": "2019-01-13T14:22:00.5404817+02:00",
    "subscriptions": [
        {
            "name": "John Doe",
            "commenced": "2019-01-13T18:54:00+02:00",
            "callbackOnModify": false,
            "created": "2019-01-13T18:51:51.8323658+02:00",
            "frequency": "Monthly",
            "action": "Renew"
            "custom": {
                "storeVisit": "2019-01-13T14:23:00.5404817+02:00"
            },
        },
        {
            "name": "698b2a63-3e11-42c9-adf8-b027c0143efa"
            "commenced": "2019-01-13T18:57:00+02:00",
            "callbackOnModify": false,
            "created": "2019-01-13T18:56:11.2166782+02:00",
            "frequency": "Weekly",
            "action": "Renew"
        }
    ],
    "custom": {
        "manufacturerNo": "D2-D1RFS-1",
        "sellOnline": false
    }
}

Update

ProductsApi
Field Type Description Constraint Object
key string API Key Required UUID
serial string Product Serial Required UUID
name string Product Name Optional
custom json Your Own JSON Optional
PUT /v1/ProductsApi HTTP/1.1
Host: keyserv.solutions
Content-Type: application/json; charset=utf-8

{
    "name": "Lawn Trimmer",
    "key": "7ecaa17b-8afb-423d-a7fc-861147ecd5f4",
    "serial":"944514ef-9263-4978-905a-7028bd0f9e6a",
    "custom": {
    "manufacturerNo":"D2-D1RFS-1",
    "sellOnline": true
    }
}

204

Delete

ProductsApi
Field Type Description Constraint Object
key string API Key Required UUID
serial string Product Serial Required UUID
DELETE /v1/ProductsApi HTTP/1.1
Host: keyserv.solutions
Content-Type: application/json; charset=utf-8

{
    "key": "7ecaa17b-8afb-423d-a7fc-861147ecd5f4",
    "serial": "944514ef-9263-4978-905a-7028bd0f9e6a"
}

410

Subscriptions

Endpoint Spec & Example Returns

List

SubscriptionsApi/Find
Field Type Description Constraint Object
key string API Key Required UUID
serial string Product Serial Required UUID
POST /v1/SubscriptionsApi/Find HTTP/1.1
Host: keyserv.solutions
Content-Type: application/json; charset=utf-8

{
    "key": "7ecaa17b-8afb-423d-a7fc-861147ecd5f4",
    "serial": "944514ef-9263-4978-905a-7028bd0f9e6a"
}

Subscriptions
[
    {
        "name": "John Doe"
        "commenced": "2019-01-20T22:03:00+02:00",
        "callbackOnModify": false,
        "created": "2019-01-20T22:00:44+02:00",
        "updated": "2019-01-20T22:03:08.873372+02:00",
        "frequency": "Monthly",
        "action": "Renew",
        "keys": [
            {
                "name": "70419b0a-aba6-4fac-b875-ca3b9ac9f131",
                "serial": "70419b0a-aba6-4fac-b875-ca3b9ac9f131",
                "current": false,
                "commenced": "2019-01-20T22:03:00+02:00",
                "callbackOnModify": false,
                "created": "2019-01-20T22:00:44.4889359+02:00",
                "frequency": "Monthly",
                "action": "Renew"
            },
            {
                "name": "John Doe",
                "serial": "a8c5536c-6583-4042-b572-9fd994365e99",
                "current": true,
                "commenced": "2019-01-20T22:03:00+02:00",
                "callbackOnModify": false,
                "created": "2019-01-20T22:02:35.7091322+02:00",
                "updated": "2019-01-20T22:03:09.0103388+02:00",
                "frequency": "Monthly",
                "action": "Renew"
            }
        ]
    },
    {
        "name": "Another Subscription",
        "commenced": "2019-01-20T22:07:00+02:00",
        "callbackOnModify": false,
        "created": "2019-01-20T22:05:05.0949729+02:00",
        "frequency": "Monthly",
        "action": "Renew",
        "keys": [
            {
                "name": "Another Subscription",
                "serial": "a7f7b9c2-0e5c-431a-9708-919f3690a196",
                "current": true,
                "commenced": "2019-01-20T22:07:00+02:00",
                "callbackOnModify": false,
                "created": "2019-01-20T22:05:05.1209604+02:00",
                "frequency": "Monthly",
                "action": "Renew"
            }
        ]
    }
]

Create

SubscriptionsApi/Save
Field Type Description Constraint Object
key string API Key Required UUID
serial string Product Serial Required UUID
frequency string Intervals:
"Monthly", "Yearly", "Quarterly", "Biennially", "Lifetime", "Daily", "Hourly", "Weekly"
Required
action string Actions:
"Renew", "Disable", "Delete", "Extend"
Required
name string Subscription Name Optional
startFrom string Supports:
ISO 8601
Unix TS
Javascript Date
DateTimeOffset
Optional Date
callbackOnModify boolean Callback When Changed Optional
callbackUrl string Your Website Endpoint Optional Url
custom json Your Own JSON Optional
POST /v1/SubscriptionsApi/Save HTTP/1.1
Host: keyserv.solutions
Content-Type: application/json; charset=utf-8

{

    "key": "7ecaa17b-8afb-423d-a7fc-861147ecd5f4",
    "serial": "944514ef-9263-4978-905a-7028bd0f9e6a",
    "frequency": "Hourly",
    "action": "Disable",
    "name": "Some New Subscription",
    "startFrom": "2019-02-17T02:20:00+02:00",
    "callbackUrl": "https://mysite.com/backend",
    "callbackOnModify": false,
    "custom": {
        "myStuff": "here"
    }
}

201 : Key
{
    "name": "Some New Subscription",
    "custom": {
        "myStuff": "here"
    },
    "serial": "bd65df70-ce00-45f7-be93-94ffcecfc3a1",
    "current": true,
    "commenced": "2019-02-17T02:20:00+02:00",
    "callbackOnModify": false,
    "created": "2019-01-21T02:13:05.2476645+02:00",
    "frequency": "Hourly",
    "action": "Disable",
    "callbackUrl": "https://mysite.com/backend"
}

Read

SubscriptionsApi/Find
Field Type Description Constraint Object
key string API Key Required UUID
serial string Any Key Serial Required UUID
POST /v1/SubscriptionsApi/Find HTTP/1.1
Host: keyserv.solutions
Content-Type: application/json; charset=utf-8

{
    "key": "7ecaa17b-8afb-423d-a7fc-861147ecd5f4",
    "serial": "bd65df70-ce00-45f7-be93-94ffcecfc3a1"
}

Subscription
{
    "name": "Some New Subscription",
    "callbackUrl": "https://mysite.com/backend",
    "custom": {
        "myStuff": "here"
    },
    "keys": [
        {
            "name": "Some New Subscription",
            "callbackUrl": "https://mysite.com/backend",
            "custom": {
                "myStuff": "here"
            },
            "serial": "bd65df70-ce00-45f7-be93-94ffcecfc3a1",
            "current": true,
            "commenced": "2019-02-17T02:20:00+02:00",
            "callbackOnModify": false,
            "created": "2019-01-21T02:13:05.2476645+02:00",
            "frequency": "Hourly",
            "action": "Disable"
        }
    ],
    "commenced": "2019-02-17T02:20:00+02:00",
    "callbackOnModify": false,
    "created": "2019-01-21T02:13:04.5826666+02:00",
    "frequency": "Hourly",
    "action": "Disable"
}

Update

SubscriptionsApi
Field Type Description Constraint Object
key string API Key Required UUID
serial string Any Key Serial Required UUID
frequency string Intervals:
"Monthly", "Yearly", "Quarterly", "Biennially", "Lifetime", "Daily", "Hourly", "Weekly"
Required
action string Actions:
"Renew", "Disable", "Delete", "Extend"
Required
name string Subscription Name Optional
startFrom string Supports:
ISO 8601
Unix TS
Javascript Date
DateTimeOffset
Optional Date
callbackOnModify boolean Callback When Changed Optional
callbackUrl string Your Website Endpoint Optional Url
custom json Your Own JSON Optional
PATCH /v1/SubscriptionsApi/ HTTP/1.1
Host: keyserv.solutions
Content-Type: application/json; charset=utf-8

{

    "key": "7ecaa17b-8afb-423d-a7fc-861147ecd5f4",
    "serial": "bd65df70-ce00-45f7-be93-94ffcecfc3a1",
    "frequency": "Hourly",
    "action": "Delete",
    "name": "Some New Subscription",
    "startFrom": "2019-02-17T02:20:00+02:00",
    "callbackUrl": "https://mysite.com/backend",
    "callbackOnModify": true,
    "custom": {
        "myStuff": "changed"
    }
}

204

Delete

SubscriptionsApi
Field Type Description Constraint Object
key string API Key Required UUID
serial string Any Key Serial Required UUID
DELETE /v1/SubscriptionsApi HTTP/1.1
Host: keyserv.solutions
Content-Type: application/json; charset=utf-8

{
    "key": "7ecaa17b-8afb-423d-a7fc-861147ecd5f4",
    "serial": "bd65df70-ce00-45f7-be93-94ffcecfc3a1"
}

410

Keys

Intended For Clients, Customers & Edge Devices

Endpoint Example Returns

Read

KeysApi/Find/{serial}
GET /KeysApi/Find/bd65df70-ce00-45f7-be93-94ffcecfc3a1 HTTP/1.1
Host: keyserv.solutions
Content-Type: application/json; charset=utf-8
Key
{
    "name": "Some New Subscription",
    "custom": {
        "myStuff": "here"
    },
    "serial": "bd65df70-ce00-45f7-be93-94ffcecfc3a1",
    "current": true,
    "commenced": "2019-02-17T02:20:00+02:00",
    "callbackOnModify": false,
    "created": "2019-01-21T02:13:05.2476645+02:00",
    "frequency": "Hourly",
    "action": "Disable",
    "callbackUrl": "https://mysite.com/backend"
}

Current

KeysApi/Current/{serial}
GET /KeysApi/Current/bd65df70-ce00-45f7-be93-94ffcecfc3a1 HTTP/1.1
Host: keyserv.solutions
Content-Type: application/json; charset=utf-8
{
    "current": true
}
{
    "current": false
}

Expiry

KeysApi/Expiry/{serial}
GET /KeysApi/Expiry/944514ef-9263-4978-905a-7028bd0f9e6a HTTP/1.1
Host: keyserv.solutions
Content-Type: application/json; charset=utf-8
{
    "expires": "2019-02-17T02:20:00+02:00",
    "time": "31.00:00:00"
}

Response Reference List

Code Type Reasons
200 OK Request Fulfilled
Return Requested Resource(s)
201 Created Resource Created Successfully
Request Completed : Resource(s)
202 Accepted Request Accepted For Further Processing
Resource To Be Deleted
204 Completed Request Completed (NFTR)
Resource Modified Successfully
304 Not Modified Resource Information Unchanged
No Update Necessary
410 Gone Resource Deleted
Resource(s) Recently Removed
402 Payment Required Subscription Upgrade Required
Tier Limit Reached
429 Too Many Requests Too Many Requests Within Short Time
Many Clients Using Same Public IP
400 Bad Request Variable Null or Invalid
Invalid Request
409 Conflict Resource With Variables Exists
Resource Name Taken
300 Ambigious Multiple Results Found
Empty Resource(s) Request
404 Not Found No Resource Found
No Such Route
412 Precondition Failed Request Doesn't Meet Requirements
Resource Missing Variables
406 Not Acceptable Resource Has Invalid Variables
Resource Data Incorrect
403 Forbidden Not Using HTTPS
Server Firewalled Resource
500 Internal Error Request Failed (Server Side)
Technical Problem (Try Again?)

Recipes

...coming soon, Raspberry PI & Arduino examples