Itheum Docs
  • 👋Getting Started
  • Infrastructure
    • 🚆AI Data Workforce
      • Token Utility for the AI Data Workforce
      • Join the Workforce
      • Liveliness Staking Rewards
    • 🖼️Data NFT
      • Data NFT Types
        • Data NFT-FT
        • Data NFT-LEASE
        • Data NFT-PH (Plug-In Hybrid)
      • Data NFT Generative Image Tool
    • 🤖NFMe ID Vaults
    • 🔋Liveliness - On-Chain Reputation
      • Data Creator Liveliness Bonding
        • Liveliness Score States
      • Liveliness Staking
      • FAQ - Liveliness staking
    • 🔓Data Marshal Network
  • Apps
    • 🔥<BiTz> XP System
      • Bonus BiTz for protocol usage
    • 💹Data NFT Marketplace
      • Listing a Data NFT
      • Procuring a Data NFT
      • FAQ - Data NFT Marketplace
    • 📡Data DEX
      • Minting a Data NFT
        • Store Data and Mint a Data NFT - Step-by-Step Tutorial
        • Creator Donations For Community Airdrops
      • Using the claims Portal
      • CanaryNet Guardrails
        • Guardrail : Trading Data NFTs on 3rd Party NFT Marketplaces
    • 🔍Itheum Explorer
  • Integrators
    • 🔋Liveliness Staking Guides
      • Liveliness Staking Guide : Solana
      • Liveliness Staking Guide : MultiversX
    • 📙Data Streams Guides
      • Data Asset Storage Options
      • Data Stream URL Rules
      • Zedge Storage
        • Static File on IPFS
        • Dymamic File on IPFS + DNS Link
        • Dymamic File on IPFS + IPNS
        • Music Data NFT Compatible Dynamic Data Stream on IPFS + IPNS
        • Trailblazer Data NFT Compatible Dynamic Data Stream on IPFS + IPNS
      • Amazon Web Services (AWS)
        • Storage : AWS S3
          • Data NFT Streaming Automation - Multiple files
          • Manual upload of file to AWS for Data NFT Streaming
          • Data NFT Streaming Automation - Trailblazer
        • Hosting : AWS S3 + Cloudflare
          • Task 1: Use a domain name to "sit in front" of your AWS S3 Bucket Public URL
          • Task 2: Convert your AWS S3 Bucket into a "website"
          • Task 3: Use Cloudflare to connect your Domain Name to your S3 Bucket securely
          • Troubleshooting
      • Akord - Arweave blockchain
      • MultiversX Native Auth Protected API
    • 📗Data DEX Guides
      • MultiversX Blockchain
        • Guide 1 : Get Started with the Data DEX on MultiversX
          • Section 1: Setting up wallets on the MultiversX Blockchain - Devnet
          • Section 2: Getting xEGLD Gas tokens to pay for transactions - MultiversX Devnet
          • Section 3: Getting ITHEUM devnet tokens via the Data DEX - MultiversX Devnet
        • Guide 2: Get Started with Itheum Enterprise
        • Itheum Ecosystem Actions Catalogue
      • Astar Network
        • Guide 1 : Get Started with the Data DEX on Astar Network
          • Section 1: Setting up wallets on Astar Network - Shibuya Testnet
          • Section 2: Getting ITHEUM devnet tokens via the Data DEX - Shibuya Testnet
        • Guide 2 : Procure Data NFTs from the peer-to-peer Data NFT Marketplace on Astar Network
        • Guide 3: Use the “Web3 Gamer Passport” App on the Astar Network to trade your PlayStation Data
    • 💳Supported Wallets
      • MultiversX DeFi Wallet
      • Ledger Wallet
      • xPortal Wallet
      • xAlias (Login with Google)
    • 📕Trailblazer Guides
      • How to Acquire a Trailblazer
      • How to view a Trailblazer
      • How to List a Trailblazer
    • 📘Data Coalition DAOs (DC DAOs) Guides
      • Appointer > Delegator Pattern for Data NFT "Deputizing"
  • Developers
    • 👨‍💻Software Development Kits (SDKs)
      • Data NFT SDK
        • Guide 1 : Minting a Custom Data NFT Collection with Authenticated Data Streams (via SDK)
        • Guide 2 : Unlocking Data NFTs via MultiversX Native Auth
        • Guide 3 : Using Nested Streams to Access Nested Data Assets from a Primary Data Stream
        • Guide 4: Use the Data NFT "Deputy" Feature to delegate access of your Data NFTs to a Smart Contract
        • Guide 5: Preparing a Data Stream containing a password to protect a URL
      • Enterprise SDK
        • Guide 1 : Using Itheum Enterprise to Mint a Data NFT Collection (e.g. NFT Loyalty Card Solution)
      • Data Marshal Network SDK
        • Guide 1 : Make your Regular NFT Collection to be Data NFT-PH Compatible
    • 🥋Data Marshal Network
      • Data Marshal Node Gateway Endpoints
      • Data Marshal Transit Flags and Headers
    • 🛂Tech Support - Discord
      • Portal Bridge Support
    • 🛒Release Notes
      • Data DEX
      • Itheum Explorer
      • Data NFT SDK
      • Enterprise SDK
      • Data Marshal Network
    • 🔐Security
      • 🐞Bug Bounty
      • ℹ️Security Audit
  • Protocol
    • $ITHEUM Token
    • 🌉Token Bridge
      • FAQ - Omni-Chain Portal Bridge
      • $ITHEUM Token Multi-Chain Max Supply Rebalancing Transactions Audit
    • 🏆Token Rewards
      • Badges
    • 🧨Token Burning
      • Phase 1 : Token Burn Program
    • 🏛️Governance
      • Itheum Ecosystem DAO
        • Version 1: How it Works
      • Itheum xPand DAO
        • Itheum xPand Grants Program
          • Code Of Conduct
          • Announcement Guidelines
          • Cohorts vs Alpha Builders
        • Program 1: MultiversX Post-Hackathon Accelerator
        • Program 2: xPand DAO Music Data NFT Growth
    • 💪Hackathons and Dev Challenges
      • MultiversX xDay Hackathon
        • Project Ideas > MultiversX Dev Tooling and Infra
        • Project Ideas > Itheum
        • Test Data NFT Catalog
      • Community Test Events
        • Portal Traveler 🌀 : Test the Itheum Omni-Chain Portal (Bridge)
        • APR for Liveliness 🎖️: Test the Bonding + Staking Rewards Module
        • Minting and Bonding on Solana
  • R&D
    • 🏢Itheum Enterprise
    • 🗳️Data Coalition DAOs (DC DAOs)
    • 🎏Trailblazer
      • FAQ - Trailblazer
  • Legal
    • ⚖️Ecosystem Tools Terms
      • Datadex
        • Terms Of Use
        • Privacy Policy
      • Liveliness Bonding: Penalties and Slashing Terms
      • BiTz XP
        • Give BiTz
      • Omni-Chain Portal Bridge
      • Gamer Passport
        • Data Collection and Storage
    • 👮Content Guidelines
    • Itheum Data License
    • Terminology Disclaimer
    • Protocol Docs, Token Disclaimer
Powered by GitBook
On this page
  • Introduction
  • Step 1: How does Native Auth protect my API?
  • Step 2: Build and Publish your Native Auth Protected API
  1. Integrators
  2. 📙Data Streams Guides

MultiversX Native Auth Protected API

PreviousAkord - Arweave blockchainNextData DEX Guides

Last updated 1 year ago

This guide is specific to using Itheum's Data NFTs in combination with the MultiversX Blockchain as it uses the Native Auth feature of MultiversX to authenticate backend services/APIs with a front-end wallet generated "token."

Introduction

If you want a backend service or API that needs to be the Data Stream API for a single Data NFT or for an entire collection of Data NFTs part of Itheum Enterprise, then this guide will provide you with a template and some steps to get you started fast. Here is how it works:

  • An end-user requests access to open your Data Stream URL (i.e., your Native Auth authenticated API).

  • The Native Auth token passes through the Itheum Data Marshal Network, which validates the user and also confirms Data NFT ownership.

  • The Data Marshal network passes through the Native Auth token and other metadata like the owner-validated NFT ID (i.e., the Data NFT ID, chain ID, etc.)

  • Your origin Data Stream API gets this request. You can then use the Native Auth token and all the injected metadata to personalize the response to the user.

An example use-case: Your origin Data Stream API can get the validated caller address and the validated Data NFT ID and use both these data points to provide real-time insights on the NFT history or behavior of the person who owns the NFT!

Step 1: How does Native Auth protect my API?

Let's understand this first. Here is an example API endpoint that's Native Auth protected : https://api.itheumcloud-stg.com/datadexapi/bespoke/dynamicSecureDataStreamDemo It's important to note that this example API gives you a "Access Forbidden as this is a protected Data Stream. No credentials sent!" message when you call it without an token like so:

curl --location 'https://api.itheumcloud-stg.com/datadexapi/bespoke/dynamicSecureDataStreamDemo'

Now, let's generate a sample Native Auth token and access the API again to test if it works. Head over to https://utils.multiversx.com/auth and swap to "devnet" and click on "Generate". Connect your wallet and it should give you a sample token. Make sure the Origin is https://utils.multiversx.com and the Time to live (seconds) is 7200.

Copy the token and use this as a Bearer token header in the API call:

curl --location 'https://api.itheumcloud-stg.com/datadexapi/bespoke/dynamicSecureDataStreamDemo' \
--header 'Authorization: Bearer ZXJk...d040b'

Now, the API will work! and the Origin Data Stream API will return a "personalized" data payload similar to this:

{
    "data_stream": {
        "name": "private stream for erd1qmsq6ej344kpn8mc9xfngjhyla3zd6lqdm4zxx6653jee6rfq3ns3fkcc7",
        "creator": "Itheum",
        "created_on": 1692571700,
        "last_modified_on": 1692571710,
        "generated_on": 1705457606
    },
    "data": [
        {
            "txId": 1001,
            "category": "purchase",
            "date": 1692571701,
            "item": "Gold Watch",
            "store": "Nice jewellers",
            "meta": "https://some_session_to_full_meta_data_of_transaction?txId=1001&user=erd1qmsq6ej344kpn8mc9xfngjhyla3zd6lqdm4zxx6653jee6rfq3ns3fkcc7&session=ZXJkMXFtc3E2ZWozNDRrcG44bWM5eGZuZ2poeWxhM3pkNmxxZG00enh4NjY1M2plZTZyZnEzbnMzZmtjYzc.YUhSMGNITTZMeTkxZEdsc2N5NXRkV3gwYVhabGNuTjRMbU52YlEuMDIwYmUxZGQ4NzEzNDAyMmY1ZGU1ZjRhMjdhM2YwZTVjMjg2NDQ0OTM3NmNiM2E3MDI1Mjg0ZDY0YzgwYWNhYS43MjAwLmV5SjBhVzFsYzNSaGJYQWlPakUzTURVME5UYzJNVEI5.c111228b165df152282222e4bd6d897a47d24f1c7fa7766806253812cb62fb40e1757894ed1b54679c4fcc1e9437f8f7ff311cdf8f3e97db7f1defd4b9cd040b"
        }
    ],
    "metaData": {
        "data_marshal_injected": {
            "itm-marshal-fwd-chainid": "error, this value should be forwarded if Data NFT was opened",
            "itm-marshal-fwd-tokenid": "error, this value should be forwarded if Data NFT was opened"
        },
        "mvx_native_auth": {
            "decodedSession": {
                "ttl": 7200,
                "origin": "https://utils.multiversx.com",
                "address": "erd1qmsq6ej344kpn8mc9xfngjhyla3zd6lqdm4zxx6653jee6rfq3ns3fkcc7",
                "signature": "",
                "blockHash": "020be1dd87134022f5de5f4a27a3f0e5c2864449376cb3a7025284d64c80acaa",
                "body": "XXX.yyy.7200.zzz",
                "extraInfo": {
                    "timestamp": 1705457610
                }
            },
            "validateSession": {
                "issued": 1705457606,
                "expires": 1705464806,
                "address": "erd1qmsq6ej344kpn8mc9xfngjhyla3zd6lqdm4zxx6653jee6rfq3ns3fkcc7",
                "origin": "https://utils.multiversx.com",
                "extraInfo": {
                    "timestamp": 1705457610
                }
            }
        }
    }
}
  • Notice how on line 3, it shows the user's address and the rest of the data stream is also personalized to the user's address used as a "identifier" to personalzied data

  • Notice how on line 20, some headers like itm-marshal-fwd-chainid and itm-marshal-fwd-tokenid are missing which will be very useful for your API, not to worry - these headers will be injected by the Data Marshal Network.

Now that we understand how Native Auth can protect our API with an authentication/authorization layer and also give us key verified metadata about the calling user so that we can personalize our response - let's proceed to the next phase and learn how you can launch our own Native Auth Protected API that can be used as a Data NFT's Data Stream.

Step 2: Build and Publish your Native Auth Protected API

  1. If your existing API already supports MultiversX Native Auth, then you are good to go! Just make sure your API conforms to the other general Data Stream URL Rules in order to use it as a Data NFT's Data Stream

  2. If your existing API does NOT support MultiversX Native Auth, you can use the following free open source templates we have published to wrap your existing API business Logic into the Native Auth Wrapper

The above API 2 templates can be used to build simple and complex APIs; the choice is yours as to which template you want to use. Or, you can use the templates to understand how to add Native Auth support and build it into your API projects.

Once your API is built as per above template and supports MultiversX Native Auth, then all you have to do is publish it to be publicly accessible you are good to go! Just make sure your API conforms to the other general Data Stream URL Rules in order to use it as a Data NFT's Data Stream

You can now use your Native Auth Protected Data Stream API URL as a Data Stream URL to mint new Data NFTs!

GitHub - Itheum/data-stream-expressjs-native-auth-wrapper-template: A Native Auth Protect API Express.js template that can be used as a Data NFT's Data StreamGitHub
A simple JavaScript Express.JS API Sample with Native Auth Support
GitHub - Itheum/data-stream-nestjs-native-auth-wrapper-template: A Native Auth Protect API Next.js template that can be used as a Data NFT's Data StreamGitHub
A complex TypeScript Next.JS API Sample with Native Auth Support. This project cna be the base for very mature production ready APIs
Logo
Logo
Drawing