Token Visibility & Access Control

This guide explains the token visibility system in VIO v4, including who can receive tokens based on their visibility type and how tokens flow between organizations.

1. Key Concepts

1.1 Organizational Hierarchy

Tenant
  ├── Tenant Direct Members (not belonging to any sub-company)
  └── Sub-Company
        └── Sub-Company Members

1.2 Three Token Visibility Types

Type	Purpose
Private	Internal use only within the creating company
Shared	Can be shared with designated partners
Public	Open to everyone

1.3 Key Terms

Creating Company: The company (Tenant or Sub-Company) that created the Token
Sharing List: The recipients configured when creating a Shared token:
- sharedWithTenants - Tenants that can access this token
- sharedWithSubCompanies - Sub-companies that can access this token
- sharedWithUsers - Individual users that can access this token

2. Tokens I Created — Who Can I Mint/Send To?

Assume you are an Admin of Company A and created a Token:

2.1 Mint to Company

This is for distributing Tokens in bulk to another company's admin, who can then distribute to their users.

Token Type	Companies You Can Mint To
Private	Only your own company ❌ Cannot mint to any other company
Shared	✅ Your own company + ✅ Companies in the sharing list
Public	✅ Any company

Business Scenarios

Private Token: Internal employee points, not meant to leave the company
Shared Token: Co-branded points with partner merchants, circulating only within the partnership network
Public Token: Universal token that can be distributed to all partners

2.2 Send to User

This is for sending Tokens directly to end users (members).

Token Type	Users You Can Send To
Private	Only Members of your own company ❌ Cannot send to anyone from other companies ❌ Cannot send to Admins (only Member role)
Shared	✅ Members of the creating company ✅ Direct members of shared tenants (excludes their sub-company members) ✅ Members of shared sub-companies ✅ Users explicitly listed in sharedWithUsers
Public	✅ Anyone

Important Details

Private Token is the most restrictive: recipient must be a Member role (not Admin) and must belong to the same company that created the Token
For Shared Tokens, "shared tenant members" means only the tenant's "direct members", NOT members of that tenant's sub-companies. To include sub-company members, you must explicitly add those sub-companies to the sharing list.

Admin Portal: Finding recipients (Send / Bulk Send)

For Public tokens:

Keyword / partial search — Finds users within your company’s scope (tenant direct members and sub-company admins).
Full email or full phone number — Exact match can resolve users anywhere on the platform.

Bulk Send uses the same resolution per row (e.g. email and amount) so external users can be found when the token is Public.

3. Tokens I Received — Who Can I Forward To?

Core Rule: When forwarding tokens received from others (tokens NOT created by your company), you can ONLY send to your own company's direct members.

Assume you are an Admin of Company B and received a Token created by Company A:

3.1 Received a Private Token

Not Possible

This scenario won't happen — Private Tokens cannot be minted or sent outside the creating company, so you cannot receive a Private Token from another company.

3.2 Received a Shared or Public Token

When forwarding tokens received from others, recipients are restricted to your company's direct members only:

Your Company Type	Recipients You Can Send To
Tenant Admin	Only direct members of your Tenant (members without sub-company affiliation)
Sub-Company Admin	Only direct members of your Sub-Company

Important

This is a security design to prevent tokens from being redistributed without limit across organizations. Regardless of the token's original visibility (Shared or Public), once you receive tokens from another company, you can only distribute them internally to your own direct members.

4. Complete Permission Matrix

4.1 Mint to Company

Token Type I Created	My Own Company	Companies in Sharing List	Any Other Company
Private	✅	❌	❌
Shared	✅	✅	❌
Public	✅	✅	✅

4.2 Send to User

Token Type (regardless of creator)	My Company Members	Sharing List Company Members	Any User
Private	✅ (Member role only)	❌	❌
Shared	⚠️ Must be in sharing scope	✅	❌
Public	✅	✅	✅

5. Typical Business Scenarios

Scenario 1: Internal Employee Points (Recommended: Private)

Create: HR creates a Private Token "Employee Points"
Distribution: Can only send to employees of the same company
Circulation: If isTransferable is enabled and TOKEN_TRANSFER feature is on, employees can transfer to each other within the company
Characteristic: Completely internal, points never leave the company

Scenario 2: Shopping Mall Alliance Points (Recommended: Shared)

Create: Mall A creates a Shared Token "Alliance Points"
Sharing Setup: Add Merchant B and Merchant C to the sharing list
Distribution: Admins of A/B/C can all send to their own members
Circulation: Members can transfer between members of A/B/C
Characteristic: Circulates within the partner network; outsiders cannot participate

Scenario 3: Universal Platform Token (Recommended: Public)

Create: Platform creates a Public Token "VIO Coin"
Distribution: Can send to any company, any user
Circulation: Completely free transfers
Characteristic: Maximum liquidity, suitable for platform-level tokens

6. Frequently Asked Questions

Q1: I received someone else's Shared or Public Token. Can I send it to my company's members?

A: Yes, but only to your company's direct members:

If you are a Tenant Admin: you can only send to members who belong directly to your Tenant (not to members of your sub-companies)
If you are a Sub-Company Admin: you can only send to members of your own Sub-Company

This restriction applies regardless of the token's original visibility (Shared or Public).

Q2: Can Private Tokens be transferred between members?

A: Yes, members CAN transfer Private Tokens to each other within the creating company, provided:

The token's isTransferable setting is enabled
The tenant's TOKEN_TRANSFER feature flag is enabled
The recipient is a Member (not Admin) of the creating company

If either setting is disabled, only admins can send Private Tokens.

Q3: Why can't sub-company members receive a Shared Token that was shared with their parent Tenant?

A: Sharing with a Tenant only includes that Tenant's "direct members" (members without sub-company affiliation). To cover sub-company members, you need to explicitly add that sub-company to sharedWithSubCompanies.

Q4: Can Token visibility be changed after creation?

A: Yes, you can modify visibility and sharing list in the Token edit interface in Admin Portal.

Q5: What happens if I change a Shared token to Private?

A: Users who already hold the token will keep their balance, but:

No new tokens can be minted/sent to users outside your company
Existing holders outside your company cannot transfer the token to anyone

7. Visual Summary

┌─────────────────────────────────────────────────────────────────────┐
│                     Token Visibility Matrix                          │
├───────────────────┬───────────────┬───────────────┬─────────────────┤
│                   │   PRIVATE     │    SHARED     │     PUBLIC      │
├───────────────────┼───────────────┼───────────────┼─────────────────┤
│ Mint to Company   │ Own company   │ Own + Sharing │ Any company     │
│                   │ only          │ list          │                 │
├───────────────────┼───────────────┼───────────────┼─────────────────┤
│ Send to User      │ Own company   │ Within sharing│ Anyone          │
│                   │ Members only  │ network       │                 │
├───────────────────┼───────────────┼───────────────┼─────────────────┤
│ Forward After     │ (Cannot       │ Own company   │ Own company     │
│ Receiving         │ receive)      │ direct members│ direct members  │
├───────────────────┼───────────────┼───────────────┼─────────────────┤
│ Typical Use Case  │ Internal      │ Partner       │ Platform-wide   │
│                   │ employee      │ alliance      │ universal       │
│                   │ rewards       │ points        │ token           │
└───────────────────┴───────────────┴───────────────┴─────────────────┘

8.1 Transfer Settings

In addition to visibility, tokens have transfer settings that affect circulation:

Setting	Description
Allow transfers between users	When disabled, only admins can send tokens; members cannot transfer to each other

Cross-tenant transfers follow visibility (there is no separate “Allow cross-tenant transfers” switch in the Admin Portal when creating or editing tokens):

Visibility	Cross-tenant transfers
Private	Not allowed
Shared	Allowed when the recipient matches the sharing configuration
Public	Allowed platform-wide, subject to recipient validation

On save, the system maps visibility to the internal cross-tenant flag (Public or Shared → enabled where applicable; Private → disabled).

8.2 Show Tokens in Parent Admin

When the Show Tokens in Parent Admin feature flag is enabled for a tenant:

Parent organization admins can see SHARED tokens created by their sub-companies
When creating a SHARED token, it is automatically shared with ancestor organizations that have this flag enabled

INFO

This feature is configured by a Super Admin at the tenant level.

Need Help?

If you have questions about token visibility or encounter unexpected behavior, contact your system administrator or super admin.

Token Visibility & Access Control ​

1. Key Concepts ​

1.1 Organizational Hierarchy ​

1.2 Three Token Visibility Types ​

1.3 Key Terms ​

2. Tokens I Created — Who Can I Mint/Send To? ​

2.1 Mint to Company ​

2.2 Send to User ​

Admin Portal: Finding recipients (Send / Bulk Send) ​

3. Tokens I Received — Who Can I Forward To? ​

3.1 Received a Private Token ​

3.2 Received a Shared or Public Token ​

4. Complete Permission Matrix ​

4.1 Mint to Company ​

4.2 Send to User ​

5. Typical Business Scenarios ​

Scenario 1: Internal Employee Points (Recommended: Private) ​

Scenario 2: Shopping Mall Alliance Points (Recommended: Shared) ​

Scenario 3: Universal Platform Token (Recommended: Public) ​

6. Frequently Asked Questions ​

Q1: I received someone else's Shared or Public Token. Can I send it to my company's members? ​

Q2: Can Private Tokens be transferred between members? ​

Q3: Why can't sub-company members receive a Shared Token that was shared with their parent Tenant? ​

Q4: Can Token visibility be changed after creation? ​

Q5: What happens if I change a Shared token to Private? ​

7. Visual Summary ​

8. Related Features ​

8.1 Transfer Settings ​

8.2 Show Tokens in Parent Admin ​