BridgeAPI Core

BridgeAPI Core is a modular, server-side Paper plugin that safely connects a Minecraft server to databases, web dashboards, OAuth providers, automation tools, and external platform integrations.

It provides the shared infrastructure used by optional BridgeAPI platform modules while remaining useful as a standalone REST API and workflow server.

BridgeAPI 0.0.2 is an early public beta. Test it on a staging server before using it in production.

Features

• Built-in Spring Boot REST API and administration endpoints
• SQLite, MySQL, PostgreSQL, and MongoDB support
• Discord, Google, and Naver OAuth2 login
• One-time verification codes for linking web accounts to Minecraft UUIDs
• Role-based API keys with optional BCrypt hashing
• Server health, player data, action log, and administration APIs
• Offline inventory, level, location, and quest-state storage
• SQL leases and optimistic version checks for safe player-state updates
• Discord membership revalidation for whitelist enforcement
• Asynchronous database and external API processing
• Optional Redis integration for multi-server communication and durable action logs
• Custom .bga API routes with JSONC comments
• BridgeFlow workflows with conditions, fallback Actions, caching, rate limiting, idempotency, circuit breakers, and safe outbound HTTP
• A main-thread bridge for Bukkit and Paper operations
• Korean and English runtime messages
• Korean, English, Chinese, and Japanese documentation

BridgeFlow and BGA

BridgeAPI includes BridgeFlow, a restricted workflow engine controlled through .bga files.

BGA stands for BridGe API and uses strict JSONC syntax. It supports comments, validated input fields, conditional steps, fallback Actions, variables, response templates, and module-provided Actions.

BGA workflows cannot execute arbitrary Java code. Privileged Bukkit and command Actions must be connected only to authenticated routes with appropriate API-key roles.

A separate VS Code extension is available from the GitHub repository for BGA syntax highlighting, schema validation, hover documentation, diagnostics, and context-aware completion.

Security

BridgeAPI is designed around explicit security boundaries:

• Bukkit world and player mutations return to the Paper main thread.
• API keys, OAuth secrets, database passwords, and tokens are sanitized from error responses.
• API keys can be restricted by role and client address.
• Scoped API keys can be stored as BCrypt hashes.
• SQL and definition paths are prevented from escaping the plugin directory.
• Outbound workflow HTTP requests require HTTPS and an explicit host allowlist.
• Private and special-use addresses are blocked by default for outbound HTTP.
• Request sizes, response sizes, queues, timeouts, retries, and workflow complexity are bounded.
• Failed BGA reloads preserve the last known-good snapshot.

The embedded web server uses port 8080 by default. Do not expose this port directly to the public internet. Bind it to 127.0.0.1 when possible, or place it behind an HTTPS reverse proxy with firewall and trusted-proxy configuration.

Requirements

• Java 25
• Paper 26.2
• A dedicated Minecraft server
• No client-side mod is required

Optional infrastructure:

• MySQL or PostgreSQL for shared multi-server player state
• Redis for distributed rate limits, cache, messaging, and durable action-log delivery
• MongoDB for supported general data storage
• Discord, Google, or Naver developer credentials for OAuth features

Strong offline-player state mutation is supported only with SQLite, MySQL, or PostgreSQL. Multi-server deployments should use a shared MySQL or PostgreSQL database.

Installation

1. Download BridgeAPI-0.0.2.jar.
2. Place it in the server's plugins directory.
3. Start the Paper server once.
4. Review the generated files in plugins/BridgeAPI/.
5. Replace the automatically generated API key with a managed secret.
6. Configure the database, OAuth providers, network binding, and optional Redis connection.
7. Restart the server.
8. Run /bridgeapi health to inspect the installation.

Commands

• /bridgeapi health [component]
• /bridgeapi api reload
• /bridgeapi database reload <relative-sql-path>
• /verify
• /인증

Administrative commands require the bridgeapi.admin permission.

Platform modules

BridgeAPI Core does not bundle every external platform integration.

CHZZK, YouTube, Discord Bot, and other platform-specific integrations are distributed as separate BridgeAPI plugins. Those modules depend on BridgeAPI Core and reuse its database, authentication, web server, error handling, and main-thread safety infrastructure.

Documentation

• Documentation language selector
• Korean
• English
• Chinese
• Japanese

Support and source

• Source code
• Issue tracker

BridgeAPI is open source under the MIT License.

You may include the Modrinth-hosted BridgeAPI file in Modrinth modpacks, subject to the MIT License.