Using the API Mode

Flex Pro Flex Alpha

These pages discuss accessing the API for the purposes of using the API Response Mode. Typically, this would be used for tag authentication.

If you are planning to use the API to modify tag data, then you need to use the Management API.

Accessing the API

The ixkio API is accessed at the following endpoint via :

GET https://api.ixkio.com/v1/t

All requests must be over HTTPS

Early ixkio users might have accessed the API via https://t.ixkio.com/k. We would recommend updating to the new v1 endpoint as soon as possible.

You can access the API either by using the XUID, or the CUID and AID, or the UID and AID.

Parameters should be passed in the query string as follows :

XUID (Required*)

x={XUID}

Example : GET https://api.ixkio.com/v1/t?x=abcd1234

The Tag Code (XUID) needs to be added to all API GET requests unless you wish to access the tag using your CUID or UID.

As the XUID is unique across the entire ixkio platform, there is no need to include any additional identifier or your AID with this request type.

If you are not using authentication tags, then this can be the only parameter you need to include to generate a response from the API.

CUID or UID (Optional*)

c={CUID}

Example : GET https://api.ixkio.com/v1/t?c=yourcode&a=abc123

or

u={UID}

Example : GET https://api.ixkio.com/v1/t?u=04AABBCC112233&a=abc123

If you access the API using the CUID or UID, then you do not need to include the XUID in the API request. However, you must also include your AID (Account ID). The UID or CUID data must have been uploaded into the ixkio platform prior to the API request.

The CUID parameter is case sensitive search - ABC123 is not the same CUID as abc123. The UID parameter must always be uppercase.

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 this example, we will assume that a simple configuration has been created with an Active Folder > Tag Group (standard type) > Batch > Tag Code. We will also assume that a 'Default API Response' has been set at the Tag Group level. In this example, we will simply use a Default API Response of 'Found'. We will be testing a tag XUID of 'q8w3sbcz'.

The API request is made to :

GET https://api.ixkio.com/v1/t?x=q8w3sbcz

The API will return a JSON response in the format :

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

Error responses will be provided as :

{
	"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

will generate a successful response of :

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

(where 'Found' is the API Response entered into your Tag Group or Tag Code Rule)

However, a failed response for an incorrect AID will return an error :

{
	"xuid": "",
	"cuid": "yourcuid",
	"error": "aid_not_found"
}

where a not found CUID will return :

{
	"xuid": "",
	"cuid": "yourcuid",
	"error": "cuid_not_found"
}

For API information for authentication NFC tags, read the API Mode for Authentication.

The HTTP response status code for all responses is 200 OK.

API settings

API settings are controlled at the Folder level and affect all Tag Groups, Batches and Tags under that Folder. It's possible to set different API settings on different Folders to allow different access options.

Navigate to the API Folder Level, then the API Settings panel to make changes to the settings.

API Tokens

By default, access to your API does not require any token. However, you can set token access in the API settings to restrict access.

An alphanumeric token up to 32 characters in length can be added into the API Token field.

The API Token can then be passed in either GET query string using the parameter 'r', for example :

r={API_TOKEN}

Example : GET https://api.ixkio.com/v1/t?x=abcd1234&r=yourapitoken

Alternatively, you can pass the token in the GET Header request using any one of the keys X-API-Key, X-Api-Key or Ixkio-R.

CORS

CORS (Cross-Origin Resource Sharing) is a security mechanism designed to control which domains a browser can access resources from. For most use cases, you can leave this field blank but for some use cases, you can modify the Access-Control-Allow-Origin response.

No setting (default)

If you leave the CORS setting blank, then the API response will be returned without an Access-Control-Allow-Origin header.

*

Entering a * into the CORS field will allow access from any domain.

Domain

Entering a specific domain, such as https://seritag.com (no trailing slash), will activate the Access-Control-Allow-Origin header response with the value of the domain entered. The CORS field will accept a single domain value up to 100 characters in length.

Rate Limits

Access to the API is rate limited and monitored to maintain overall service levels. However, under all normal use cases users would not hit any limits.

We will contact you if our systems flag any unusual or high volume access.

Using Authentication NFC Tags

Authentication NFC tags need to be encoded by Seritag (ixkio's sister company) to be used on the ixkio platform. Seritag will encode the tags for your project and upload the encryption keys directly to the platform ready for use.

We strongly recommend discussing your requirements with us before proceeding but the general process is :

1. Contact us to discuss or inform us of required NFC tag type

2. Create your Active Folder, Authentication Tag Group and Batch

3. Add the required number of Tag Codes into your Batch

4. Contact us with details of where you have created your Tag Codes

5. We encode your tags for the platform and upload the encryption keys

Because the use of the API system requires the NFC tags to be encoded with your site URL, the tags will never have our platform URL encoded on them. However, each tag used with the ixkio platform for authentication still needs it's unique Tag Code - even if you never actually use the XUID itself.

We strongly advise creating a new Batch for each set of authentication tags, even if it's simply a repeat order.

For some guidance, read using the API Mode for Authentication.