Entitlements Quick Reference

Quick reference card for SoulWars administrators.

Admin Access

Requirements: Admin, moderator, or super_admin permission

Default Entitlements

ID	Purpose
game_access	Launch matches, play game, use chat
theme_creator	Access theme creation tool
theme:*	Access to specific premium themes

Quick Actions

1

Grant Game Access to New User

• Admin panel → "Grant Entitlement"

• Search user by wallet/username

• Select user from results

• Entitlement: "Game Access"

• Grant Type: "Admin Grant"

• Leave expiration blank

• Click "Grant Entitlement"

2

Create New Theme Entitlement

• Admin panel → "Manage Entitlements"

• Entitlement ID: theme:your-theme-id

• Name: "Your Theme Name"

• Category: "Theme"

• Click "Create Entitlement"

3

Give 7-Day Trial

• Admin panel → "Grant Entitlement"

• Find and select user

• Choose entitlement

• Grant Type: "Trial"

• Expires At: [7 days from now]

• Click "Grant Entitlement"

4

Revoke Access

• Admin panel → "View User Entitlements"

• Enter User ID

• Click "View"

• Find entitlement to remove

• Click "Revoke"

• Confirm

Entitlement Naming Rules

Game Features: feature_name

• Examples: tournament_access, ranked_matches

Themes: theme:theme-id

• Examples: theme:cyberpunk, theme:medieval

• Note: Default theme needs no entitlement

Tools: tool_name

• Examples: map_editor, theme_creator

Grant Types

• Admin Grant: Manual access given by admin

• Trial: Temporary trial period

• Gift: Promotion or reward

• Purchased: User bought it (usually automatic)

• Creator: For content creators/owners

Common Issues

User can't access feature

• Check entitlements for the user

• Verify entitlement is not expired

• Ask user to refresh the page

"Already has entitlement" error

• Revoke the old entitlement, then grant the new one

Can't access admin panel

• Check permissions table

• Verify correct wallet is connected

Theme not working

• Verify ID format: theme:theme-id (with colon)

API Endpoints

Check user entitlements:

GET /api/entitlements/user/:userId

Grant entitlement (admin only):

POST /api/entitlements/grant
Body: { userId, targetUserId, entitlementId, entitlementType, expiresAt, notes }

Search users (admin only):

GET /api/entitlements/search-users?query=searchTerm&userId=adminId

SQL Quick Commands

Grant game access directly:

INSERT INTO user_entitlements (user_id, entitlement_id, entitlement_type)
VALUES (USER_ID, 'game_access', 'admin');

Check user's entitlements:

SELECT e.name, ue.* 
FROM user_entitlements ue
JOIN entitlements e ON e.id = ue.entitlement_id
WHERE ue.user_id = USER_ID
  AND (ue.expires_at IS NULL OR ue.expires_at > NOW());

List all entitlements:

SELECT * FROM entitlements WHERE is_active = TRUE;

Best Practices

• Always add notes when granting

• Use trial type for temporary access

• Set expiration dates for trials

• Double-check user before granting

• Revoke test accounts regularly

Full Documentation

• Architecture Guide - Technical details

• User Guide - Complete admin manual