Quick Start

To Keep by Feenics™ API

Use this Quick Start guide to step through the process of provisioning a Standard instance. In this guide we assume that an instance has already been created and an administrator account added to the instance.

The guide will perform the following tasks:

  • Setup for Development
  • Confirm that the workstation can reach the API server
  • Login to the Instance with the provided administrator user-name and password
  • Create an Access Level
  • Create a Schedule for weekday access from 9am to 5pm
  • Create a Badge Type for Employees with suitable defaults
  • Adding a new Person
  • Assigning cards to a Person
  • Adding Multiple People via Batch
  • Add a Single door, two reader panel
  • Link the readers to the access level
  • Simulate a card read
  • Query Event History for an Access Granted event
  • Walk through Modifying an existing Person

Setup for Development

Lets get setup to use all the cool features in the API that is going to be discussed below. The first step is to acquire or open an Integrated Development Environment. We mainly use Visual Studio and/or LINQPad. Next, you will need to install several NuGet Packages into your choice of IDE. The ones you need are listed below.

NuGet Sources and Packages:

The Feenics nugets will ask to also install any dependent nugets, which should be most of the ones listed in the nuget.org section below.

Now that the Above packages are installed you should be able to use the Keep API.

Get the server information

The endpoint for the MQTT service is returned when getting the SysInfo object from: https://keepapi.feenicshosting.com/api/sysinfo

Example in C#

var client = new Client("https://keepapi.feenicshosting.com");
var sysInfo = await client.GetSysInfo();

Example in CURL

curl -s https://keepapi.feenicshosting.com/api/sysinfo | json_pp

{
  "ServerTime": "2018-05-04T18:46:58.6746458Z",
  "Version": "1.0.6694.34947",
  "$type": "Feenics.Keep.WebApi.Model.SysInfo, Feenics.Keep.WebApi.Model",
  "ServerId": "i-04efd735"
}

Throughout this exercise we will be working with the following constants:

Name Value Purpose
BaseAddress https://keepapi.feenicshosting.com The scheme (https) and endpoint of the Keep by Feenics Service
InstanceName QuickStart Everything in Keep is segregated into a hierarchy of instances. For this walk-through the instance name we’ll use is QuickStart. Refer to your Developer Welcome Letter for your own developer instance name
Username admin The user-name that you will use to authenticate with Keep
Password adminpass The password text that you will use to authenticate with Keep

As we create new variables in an exercise we will consider them available for reuse in a future exercise. This helps us create cleaner and more concise code snippets for you to observe.

To confirm that the workstation can reach the Keep by Feenics™ service issue a simple GET request using curl. Append to the base address the resource identifier /api/sysinfo. You may find it convenient to format the results using json_pp.

Notice that if you run the same curl command repeatedly you should receive different ServerId values. This confirms that there are multiple servers responding to the request. The exact number of servers will vary from time to time, as load on the environment fluctuates.

Login To The Instance

Example in C#

var client = new Client("https://keepapi.feenicshosting.com");
var (isLoggedIn, loginError, loginErrorMsg) = await client.LoginAsync("yourInstanceName", "yourUserName","yourPassword");
if(!isLoggedIn)
{
    Console.WriteLine($"Failed to login. {loginError} - {loginErrorMsg}");
}

Example in CURL

curl -X POST \
  https://keepapi.feenicshosting.com/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=password&client_id=consoleApp&client_secret=consoleSecret&username=YOUR_USERNAME&password=YOUR_PASSWORD&instance=INSTANCE_FQDN&sendonetimepassword=false&undefined='

To request a new access token

Example in C#

var token = await client.RefreshAsync()

Example in CURL

curl -X POST \
  https://keepapi.feenicshosting.com/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'refresh_token=REFRESH_TOKEN_HERE&grant_type=refresh_token&client_id=consoleApp&client_secret=consoleSecret&undefined='

The above commands return JSON structured data like this:

{
  "instance": "5ae23119a3ac160dd82dd5eb",
  "userName": "LOGININSTANCE\\yourUserName",
  "as:client_id": "consoleApp",
  "refresh_token": "5af040aca3ac160df4ba26dc",
  "token_type": "bearer",
  ".expires": "Tue, 08 May 2018 12:03:56 GMT",
  "expires_in": 86399,
  ".issued": "Mon, 07 May 2018 12:03:56 GMT",
  "access_token": "ld1oJz5ZaU0DOrVFr44KbrOE1MbC91GvJv_-cb2DfVbaGFJ67Z6fqZKDQZYee8XnFohW3iKfNzsIjiOLUmINFsZ_f2KrcmAPajA-KJM0oS_itkIwtRJy2DwJTElOMf4eH1y9aEere93jflj2fs7nMsgo_AeQPB2S-u9AsZcKhJJvncOS-k-tsmUylHCnRgV2J-uDZaxyRcVgU99sDqffUv8x_mAsu0WUUcrUvfOyDq3NQVIRRTwpEvMxDGyUhlZBAHkpckSOzd_NE-RUAXY-8HN_LMFOPJu8LMnvH1iDPhTv9gnVvKOqH3J3TJii1KGt4ZI24Oj389HzP2BD-PXGYMVFat3CZV4QIWNFYfBkkr_NvOKT_1kmDYmKbkbU3IpJ"
}

It’s important to remember that Hypertext Transfer Protocol is a connection-less application protocol. As such, no connection to a server is maintained; as would be the case with an Open Database Connection (ODBC) to a database server, for example.

Rather, the login process simply transmits (POST) a request to the Application Service for an access token, providing valid credentials (instance name, username, and password).

If the instance name, username and password are all correct, the server will return a JWT (JSON Web Token), which will contain the access_token. This access token must be provided in the header of all subsequent API requests to the service.

When using the .NET Wrapper library all the token management, etc is handled for you. When using cURL it might be helpful to store the token in secure way; any more cURL examples may assume you have a token and will use token bearer authorization.