Blue Bite Rolling Key API

Table of Contents

Overview

The Blue Bite Rolling Key API is a great way to host exclusive content on any domain you control and utilize a powerful feature of NFC inlays. Blue Bite offers special NFC inlays (Rolling Code NFC Tags) that guarantee a user physically tapped the inlay, and 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 physically 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
    1. Redirect from one-time NFC URL: https://mtag.io/xxxx?uid={UID}&token={TOKEN}
    2. To external domain: https://example.com?rk={ROLLINGKEY}
  2. External domain validates Blue Bite Rolling Key API
  3. External domain Receive NFC interaction payload with verification status
    1. For NFC Verification, look for tag_verified property. Returned values are: true || false || null

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

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

Params

URL ParameterRequiredExampleDescription
rkMnkxMFhDWmRkbXIwTFlXYXp4WXVXNk9uQU1TMVNhQ3hyYnl3QzR1Y1l3QVdFOGRWOW5PRHJkU1c=Base64 encode the given rolling key (rk) parameter from the initial URL redirect

Example

Flow
Redirect URL
https://example.com/nfc_page?rk=2y10XCZddmr0LYWazxYuW6OnAMS1SaCxrbywC4ucYwAWE8dV9nODrdSW

Base64 Encode
2y10XCZddmr0LYWazxYuW6OnAMS1SaCxrbywC4ucYwAWE8dV9nODrdSW → Base64 → MnkxMFhDWmRkbXIwTFlXYXp4WXVXNk9uQU1TMVNhQ3hyYnl3QzR1Y1l3QVdFOGRWOW5PRHJkU1c=

GET
https://api.mtag.io/v2/interactions/rk_payload?rk=MnkxMFhDWmRkbXIwTFlXYXp4WXVXNk9uQU1TMVNhQ3hyYnl3QzR1Y1l3QVdFOGRWOW5PRHJkU1c=

Example Request

Example Request - Valid
curl --request GET \
  --url 'https://api.mtag.io/v2/interactions/rk_payload?rk=MnkxMFhDWmRkbXIwTFlXYXp4WXVXNk9uQU1TMVNhQ3hyYnl3QzR1Y1l3QVdFOGRWOW5PRHJkU1c='

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": "2y10XCZddmr0LYWazxYuW6OnAMS1SaCxrbywC4ucYwAWE8dV9nODrdSW"
}