EXTERNAL SERVICES

API Keys & External Integrations

VIRCON integrates with VRChat API for member synchronization, Discord webhooks for external notifications, and internal authentication for dashboard access. API keys are encrypted, monitored for failures, and rotatable for security.

API Key Commands

Commands for managing VRChat authentication, Discord webhooks, and API key rotation.

,keys list - View all configured API keys and integration statuses
,keys vrchat set <auth_cookie> - Configure VRChat API authentication
,keys vrchat test - Verify VRChat API connectivity
,keys webhook add <url> [label] - Add Discord webhook for notifications
,keys webhook remove <webhook_id> - Remove Discord webhook
,keys rotate all - Regenerate all internal API keys (emergency use)

Supported Integrations

External services integrated with VIRCON for cross-platform functionality.

VRChat API

Purpose: Member sync, group management, world tracking, online status

Authentication: Session cookie (auth cookie from browser)

Permissions: Group admin required to manage members and roles

Discord Webhooks

Purpose: External notifications for incidents, alerts, and reports

Authentication: Webhook URL (OAuth 2.0 based)

Permissions: Manage Webhooks permission in target channel

Internal Bot API

Purpose: Dashboard backend communication and command proxying

Authentication: JWT tokens signed with bot secret key

Permissions: Role-based access control via Discord roles

VRChat API Integration Workflow

Step-by-step process for configuring and maintaining VRChat API authentication.

1. Admin obtains VRChat auth cookie from browser session (authenticated login).
2. Admin runs ,keys vrchat set <auth_cookie> to configure authentication.
3. Bot validates cookie by making test API call to VRChat user info endpoint.
4. If valid, cookie encrypted and stored in bot configuration database.
5. Bot uses cookie to sync VRChat group members to Discord database.
6. Sync runs automatically every 30 minutes, uses incremental updates to minimize API calls.
7. Bot monitors for 401 errors indicating cookie expiration, alerts admin to refresh.
8. Admin regenerates cookie when notified and updates via same command.

Discord Webhook Workflow

Process for adding, testing, and managing Discord webhooks for notifications.

1. Admin creates Discord webhook in target notification channel.
2. Admin copies webhook URL from Discord channel settings.
3. Admin runs ,keys webhook add <url> "Incident Alerts" to register webhook.
4. Bot validates webhook by sending test message to verify connectivity.
5. Webhook added to database with label for identification.
6. When incidents or alerts trigger, bot sends formatted embed via webhook.
7. Admin can view all webhooks with ,keys list command.
8. Remove webhook with ,keys webhook remove <id> when no longer needed.

API Key Database Schema

Database structure for encrypted key storage, usage tracking, and failure monitoring.

Field	Description
key_id	Unique key identifier.
service_type	vrchat, discord_webhook, internal_api.
key_label	Human-readable label (e.g., 'Incident Webhook').
encrypted_key	Encrypted API key or auth token.
created_at	When key was first configured.
created_by	Discord ID of admin who created key.
last_used_at	Most recent successful API call timestamp.
last_rotated_at	When key was last regenerated (for internal keys).
status	active, expired, revoked, pending_validation.
failure_count	Consecutive failed API calls (trigger alerts at 5+).

Security Measures

Encryption, access controls, and security practices protecting sensitive API credentials.

All API keys encrypted at rest using AES-256 with bot master key.
VRChat auth cookies NEVER logged to console or audit trail (redacted).
API keys stored in separate config database with restricted file permissions.
Internal API tokens use short expiration (24h) with automatic rotation.
Failed API calls tracked - 5+ consecutive failures trigger expiration alert.
Key rotation command regenerates all internal keys simultaneously.

Integration Use Cases

Practical examples of external integrations enhancing automation and notifications.

Case 1

VRChat group member joins via VRChat platform

Integration: VRChat API sync pulls new member

Outcome: Bot detects new member, creates Discord database entry, runs trust check

Case 2

High-severity incident created by moderator

Integration: Discord webhook sends notification to leadership channel

Outcome: Council receives immediate alert with incident summary and action buttons

Case 3

Dashboard user logs in to view moderation metrics

Integration: Internal API validates JWT token and user permissions

Outcome: Dashboard backend authorizes request, returns filtered data based on role

Troubleshooting Guide

Common integration issues with diagnostic steps and solutions.

VRChat Sync Failing - 401 Unauthorized

Cause: VRChat auth cookie expired or invalidated by password change

Solution: Log into VRChat website, copy new auth cookie, run ,keys vrchat set

Webhook Messages Not Sending

Cause: Webhook deleted or channel permissions changed

Solution: Recreate webhook in Discord, update bot with ,keys webhook add

Dashboard Login Fails - Invalid Token

Cause: Internal API key rotated or JWT secret changed

Solution: Clear browser cache, re-login to dashboard to get fresh token

Best Practices

Guidelines for secure and reliable management of external service integrations.

Rotate VRChat auth cookie monthly or after any VRChat password change.
Use descriptive labels for webhooks to identify their purpose quickly.
Test integrations after configuration with dedicated test commands.
Monitor API failure counts weekly to catch expiration before total failure.
Keep backup of VRChat auth cookie in secure vault in case of emergency rotation.
Restrict ,keys commands to head admin role minimum (sensitive operation).

Limitations & Rate Limits

Platform-specific rate limits and integration constraints to be aware of.

VRChat API rate limited to 100 requests/minute - bot respects limits automatically.
Discord webhooks cannot send more than 30 messages/minute per webhook.
VRChat auth cookies expire when user changes password or logs out all sessions.
Internal API tokens tied to bot secret key - bot restart required on rotation.
API key encryption strength depends on bot master key security (guard carefully).