API Mode for Authentication

Flex Pro Flex Alpha

The API Response Mode for use with authentication tags is similar to standard tags. For the authentication system to work :

• You must be using authentication NFC Tags (NTAG424 for example)

• The tag keys must have been loaded into the ixkio platform (how to check)

As the authentication system will only work using a unique code generated by the authentication NFC tag, we recommend testing and developing with a set of working NFC tags. Contact us for options.

API Response

The API Response will follow the Rules configured for that Tag Code (or inherited by that Tag Code from the Tag Group).

For the authentication system to work correctly, we need to create a Rule Group that will activate on a successful authentication and provide a Response and then, on a fail, will fall back to the Default Response.

Example Configuration

For this example, we will assume that a simple configuration has been created with an Active Folder > Tag Group (authentication type) > Batch > Tag Code. You will also need a sample authentication NFC tag associated with this Tag Code. (It's possible that if we have provided some sample tags, we will already have configured the Rules as detailed for you. You can, of course, change them.)

For this example, we are going to set a Rule at the Tag Group level. It is possible to set the rule for each individual Tag Code as well.

At the Tag Group level, you need to create the Authentication Rule Group. On the Tag Group screen, under Tag Group Function Panel > Ruleset Tab, click on 'Add Rule Group'. Click the small burger menu on the right, then 'Add New Rule'. Select 'Tag Authentication', then 'Authentication Pass'.

You will now have two empty 'Response' fields.

The first is for the 'Rule Group API Response' - which is the response given on a successful authentication. Enter 'Pass' into this field.

The second is the Default API Response. This is the response if the authentication is not successful (ie, a fail). Enter 'Fail' into this field.

Then click 'Save Changes'.

Testing

We will be testing a tag XUID of 'q8w3sbcz'. The sample NFC tag will have been configured to hit your server first. So you will need to extract the correct parameters from the URL query string.

There are a few ways that this can be configured - see notes below - but we will explain the standard method.

Step 1 : The Tag Scan

On scanning the NFC tag, the URL will be presented as follows :

https://yourdomain.com/auth?x=q8w3sbcz&n=000001&e=abcde12345abcde1234

(Where, in this example, yourdomain.com is your website and auth is your page handling the tag scans)

Step 2 : Your Server Request

Your server needs to extract the x, n and e parameters and make an API call to our server as follows :

GET https://api.ixkio.com/v1/t?x=q8w3sbcz&n=000001&e=abcde12345abcde1234

Remember that both the n and e parameters will change on every scan. You should only test directly from each tag scan and don't change the parameters in any way until you are comfortable with the platform.

Step 3 : The Response

The ixkio platform will now respond to your API request after checking the authentication. Based on the Rules we have created, a successful authentication would return :

{
	"xuid": "q8w3sbcz",
	"response": "Pass"
}

If the authentication fails, the response would be :

{
	"xuid": "q8w3sbcz",
	"response": "Fail"
}

An error in the request would be, for example :

{
	"xuid": "q8w3sbcz",
	"error": "batch_inactive"
}

Response to CUID or UID requests

If your request is via the CUID or UID method, then a successful response will return only the CUID and the associated XUID. For example, a request for :

GET https://api.ixkio.com/v1/t?a=youraid&c=yourcuid&n=000001&e=abcde12345abcde1234

will generate a successful response of :

{
	"xuid": "q8w3sbcz",
	"cuid": "yourcuid",
	"response": "Pass"
}

The 'n' Parameter

The 'n' parameter passes the ixkio platform the scan count from the NFC chip itself (in hexadecimal). This is not the same as the ixkio scan count as explained in our Chip Count vs. Scan Count page.

The ixkio platform uses the chip count along with the unique tag 'auth' code (the 'e' parameter) to authenticate. Each 'n' chip count will have a matching 'e' auth code. If they are out of sync, then the response will be a fail.

Some important points :

Ixkio will believe you

Ixkio will believe whatever 'n' chip count parameter you send it.

The chip count can only move forward

The chip count can never go backwards on the ixkio platform. If you accidently set the chip count to 1,000, then only a genuine tag scan from 1,001 onwards will now work. You cannot 'reset' the chip count on the ixkio platform.

Single use

Once a chip count has been used, it is instantly no longer valid. If you 'refresh' the API request, you will get a failed authentication.