API Reference

VIO v4 provides two sets of APIs for different integration scenarios.

External API

The External API is a REST API for tenant-level integrations. It uses API key authentication and provides full CRUD access to platform resources.

Use the External API when you want to:

• Integrate your backend systems with VIO
• Automate voucher creation and management
• Manage users programmatically
• Build custom dashboards with analytics data
• Handle token minting, burning, and transfers from your server

Feature	Details
Auth	API Key via X-API-Key header
Base URL	https://{your-domain}/api/external/v1
Rate Limit	60 req/min, 10,000 req/day
Format	JSON request/response

API sections: Vouchers | Users | Campaigns | Tokens | Analytics

---

Mini App API

The Mini App API is designed for third-party web apps that are embedded inside the VIO Member App via an iframe. It uses JWT-based authentication (refresh/access tokens).

Use the Mini App API when you want to:

• Build a mini app that runs inside the VIO Member App
• Access the current user's profile and wallet data
• Display token balances and voucher listings
• Send tokens or issue vouchers to users (admin role)
• Create interactive experiences within the VIO ecosystem

Feature	Details
Auth	JWT (refresh token -> access token)
Base URL	https://api.vio.com/api/miniapp
Embedding	iframe inside VIO Member App
Format	JSON request/response

API sections: Auth | User Info | Tokens | Vouchers | Admin Actions | Public APIs

---

Public APIs

The Public API provides endpoints that don't require authentication, useful for mini apps that need to perform initial operations before user login.

Use the Public API when you want to:

• Verify a redemption PIN to identify a tenant
• Get a list of stores for a tenant
• Retrieve tenant branding information for UI customization

Feature	Details
Auth	None required
Base URL	https://api.vio.com/api/public
Format	JSON request/response

Endpoints:

Method	Endpoint	Description
POST	/verify-pin	Verify PIN and get tenant info
GET	/tenants/:tenantId/stores	Get stores list for a tenant
GET	/tenants/:tenantId/info	Get tenant public info and branding

See Public APIs documentation for details.

---

---

Web3 Asset Service

The platform uses an external Web3 Asset Service for on-chain operations. This service manages ERC-20 token contracts, ERC-721 NFT contracts, and custodial wallets.

Feature	Details
Auth	X-API-Key header
Docs	Swagger UI
Capabilities	Wallet creation, Token deploy/mint/transfer/burn/recall, NFT deploy/mint/transfer

Key points:

• Every user gets an auto-provisioned custodial wallet with a userSecretKey for signing transactions
• When a user links across tenants via Cross-Tenant SSO, all linked User records share the same wallet address (the wallet is only created once)
• Token and NFT contracts are deployed on-chain via the Web3 service when created through the Admin Portal or API
• Wallet provisioning happens automatically on user creation or lazily on first blockchain operation

---

Internal APIs (Member App & Admin Portal)

The following APIs are used internally by the VIO Member App and Admin Portal. They use JWT Bearer token authentication.

Push Notifications API

Endpoint	Method	Auth	Description
/api/users/me/push-subscription	POST	JWT	Register a Web Push subscription
/api/users/me/push-subscription	DELETE	JWT	Remove a push subscription
/api/users/me/notification-preferences	GET	JWT	Get notification preferences
/api/users/me/notification-preferences	PUT	JWT	Update notification preferences
/api/notifications/broadcast	POST	JWT (Admin)	Broadcast notification to all users
/api/notifications/send	POST	JWT (Admin)	Send notification to a specific user
/api/notifications/stats	GET	JWT (Admin)	Get push subscription statistics

WebAuthn / Biometric API

Endpoint	Method	Auth	Description
/api/auth/webauthn/register-options	POST	JWT	Generate biometric registration options
/api/auth/webauthn/register-verify	POST	JWT	Verify and store biometric credential
/api/auth/webauthn/login-options	POST	Public	Generate biometric login challenge
/api/auth/webauthn/login-verify	POST	Public	Verify biometric login, return JWT tokens
/api/auth/webauthn/credentials/:id	DELETE	JWT	Remove a biometric credential

Cross-Tenant SSO API

Enables single sign-on across tenants and sub-companies. Uses an HttpOnly cookie (vio_sso_token) for global session management. The login endpoint supports crossTenantLink, crossSubCompanyLink, and crossParentPortalLink (parent company URL vs sub-company–only profile) for account linking. Signup detection (check-identifier) and cross-tenant prompts can return sourceSubCompanyName when the existing account was created under a sub-company. See the full Cross-Tenant SSO guide for architecture details and QA test cases.

Endpoint	Method	Auth	Description
/api/auth/sso/check-identifier	POST	Public	Check if email/phone is registered in another tenant (signup detection)
/api/auth/sso/check	GET	Cookie	Check if SSO session exists for a target portal (tenant + optional sub-company)
/api/auth/sso/exchange	POST	Cookie	Exchange SSO token for portal-specific JWT
/api/auth/sso/link	POST	Cookie	Link existing portal account (password confirmation, optional subCompanyId)
/api/auth/sso/unlink	POST	JWT	Unlink a portal from global identity (optional subCompanyId)
/api/auth/sso/logout	POST	Cookie	Revoke SSO session globally
/api/auth/me/linked-tenants	GET	JWT	List all portals linked to the user's identity (includes sub-company info)
/api/auth/login	POST	Public	Login with optional crossTenantLink, crossSubCompanyLink, crossParentPortalLink; see SSO guide for prompt responses

Voucher Transfer API

APIs for transferring vouchers between users and viewing transfer history.

Endpoint	Method	Auth	Description
/api/vouchers/me/:userVoucherId/transfer	POST	JWT	Transfer a voucher to another user
/api/vouchers/me/transfer-history	GET	JWT	Get user's voucher transfer history

Transfer Voucher

Transfer a claimed voucher to another user. Transfer eligibility is determined by the voucher's visibility setting:

Visibility	Transfer Scope
Private	Only within the creating company (same tenant/sub-company)
Shared	Creating company + shared organizations (sharedWithTenants, sharedWithSubCompanies)
Public	No restrictions - can transfer to any user

Request body:

{
  "toUserId": "string"  // Recipient user ID
}

Error responses:

• 403 Forbidden - "Private vouchers can only be transferred within the creating company"
• 403 Forbidden - "Shared vouchers can only be transferred within allowed organizations"

Get Voucher Transfer History

Get the current user's voucher transfer history (sent and received).

Query parameters:

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	20	Items per page
direction	string	"all"	Filter by direction: "all", "sent", or "received"

Response:

{
  "success": true,
  "data": [
    {
      "_id": "transfer_id",
      "userVoucherId": "user_voucher_id",
      "voucherId": { "_id": "...", "name": "Voucher Name", "images": [...] },
      "fromUserId": { "_id": "...", "displayName": "Sender Name", "email": "..." },
      "toUserId": { "_id": "...", "displayName": "Recipient Name", "email": "..." },
      "voucherSnapshot": { "name": "...", "value": 100, "valueType": "fixed" },
      "transferredAt": "2024-01-15T10:30:00Z",
      "direction": "sent"  // or "received"
    }
  ],
  "pagination": { "total": 10, "page": 1, "limit": 20 }
}

---

Comparison

	External API	Mini App API	Public API
Authentication	API Key	JWT Tokens	None
Use case	Server-to-server	Client-side (iframe)	Pre-auth operations
User context	Any user (by ID)	Current logged-in user	No user context
Admin features	Full CRUD	Send tokens/vouchers	Read-only
Analytics	Yes	No	No
Rate limiting	60/min	Standard	Standard