Rolling Key API

The Blue Bite Rolling Key API is a great way to utilize a powerful feature of NFC inlays and host exclusive content on any domain you control. Blue Bite offers special NFC inlays called Rolling Code NFC Tags that guarantee a user physically tapped the inlay (meaning they did not copy and/or share the URL). Rolling Code NFC tags are useful for applications such as product authentication, content exclusivity, and any other application where user actions should be restricted to users who are in physical proximity to the NFC inlay.

Mechanism: Each time the NFC inlay is tapped, it generates a one-time URL that Blue Bite can parse and recognize.

Limitations: It is technically possible to clone the encoded URL on a one-time basis, however it is not possible to fully clone a Rolling Code NFC Tag, which makes it a suitable candidate for the aforementioned use cases.

Sample Interaction Flow

1. User taps Blue Bite NFC inlay

• Redirect from one-time NFC URL: https://mtag.io/xxxx?uid={UID}&token={TOKEN}
• To external domain: https://example.com?rk={ROLLINGKEY}

2. External domain validates Blue Bite Rolling Key API

3. External domain receives NFC interaction payload with verification status

• For NFC Verification, look for tag_verified property. Returned values are: true || false || null
• To external domain: https://example.com?rk={ROLLINGKEY}

GET Blue Bite Rolling Key

https://api.mtag.io/v2/interactions/rk_payload?rk={ROLLINGKEY}

This is a public API call that can be used to retrieve the interaction payload for a Blue Bite mTAG. The payload is a JSON object with tag, interaction and verification properties.

Issued Rolling Keys have a Time To Live (TTL) of 5 minutes from interaction time.

Response

• 200 OK { Interaction Payload }
• Rolling Key is valid & within TTL
• 200 OK [ ]
• Rolling Key is invalid and/or TTL has expired

Parameters

Example

Flow

Redirect URL
https://example.com/nfc_page?rk=2y10XCZddmr0LYWazxYuW6OnAMS​1SaCxrbywC4ucYwAWE8dV9nODrdSW

Base64 Encode
2y10XCZddmr0LYWazxYuW6OnAMS​1SaCxrbywC4ucYwAWE8dV9nODrdSW → Base64 → MnkxMFhDWmRkbXIwTFlXYXp4WXV​XNk9​uQU1TMVNhQ3hyYnl3QzR1Y1l3Q​VdFOGRWOW5PRHJkU1c=

GET
https://api.mtag.io/v2/interactions/rk_payload?rk=MnkxMFhDWmRkbXIwTFlXYXp4WXV​XNk9​uQU1TMVNhQ3hyYnl3QzR1Y1l3Q​VdFOGRWOW5PRHJkU1c=

Example Request

Example Request - Valid

curl --request GET \
   --url

https://api.mtag.io/v2/interactions/rk_payload?rk=MnkxMFhDWmRkbXIwTFlXYXp4WXV​XNk9​uQU1TMVNhQ3hyYnl3QzR1Y1l3Q​VdFOGRWOW5PRHJkU1c=

Example Response

200 OK

{
   "campaigns": [],
   "metadata": {
      "name": "Experience Studio",
      "title": "Experience",
      "description": "",
      "url": "studio-vuejs",
      "tag_id": 99999,
      "studio_id":"bluebite:es:e0c038fb-8a67-493e-9fed-2e16e2772f02",
       "widget_settings": {
           "instagrid": {
           },
           "twitter-widget": {}
           }
       },
       "language_code": "en-us",
       "verified": "1",
       "tag_verifier_enabled": "1",
       "device_id": 99999999
   },
   "app_id": 2,
   "social": {
       "blacklist": {}
   },
   "location": {
       "id": 46819918,
       "street": "121 E 24th St",
       "dma": 501,
       "lat": 40.742321,
       "lon": -73.984495,
       "stationary": true,
       "data": {
       },
       "user_data": [],
       "system": [],
       "venue": {
           "type": {
               "id": 37,
               "name": "Office",
               "stationary": 1
           },
           "name": "Blue Bite Office"
       },
       "asset": {
           "type": {
               "id": 169,
               "name": "NFC Manufacturer",
               "stationary": 1
           },
           "id": "Rolling Code NFC Inlay"
       }
   },
   "interaction_ids": [
       999999999
   ],
   "impression_ids": [],
   "track_location": true,
   "payloads": [],
   "tag_verified": true,
   "device": {
       "r": false,
       "rd": true,
       "country": "US"
   },
   "rk": "2y10XCZddmr0LYWazxYuW6OnAMS​1SaCxrbywC4ucYwAWE8dV9nODrdSW"
}