Quickstart: check the Supabase-to-Brails route

Give the Brails integration a stable outbound path while keeping the application on hosted Supabase. Start with a routing check that sends no Brails credentials, then use an authorized sandbox read to inspect API connectivity without creating a payout.

This quickstart uses the preserved helper in code/brails-check.mjs. For general Supabase proxy setup, see the existing QuotaGuard platform guide. For the full account and deployment discussion, see the Brails technical guide.

Have these ready

• A Supabase project and an existing operator-only diagnostic path.
• A QuotaGuard subscription with its exact HTTP or HTTPS connection URL and assigned IP pair.
• The correct Brails sandbox account and permission to read it if you will use wallets mode.
• Confirmation that the chosen proxy region and shared or dedicated address type fit the Brails account’s policy.
• IPv4 reachability to the sandbox destination through that route.

When Brails allowlisting is enabled, arrange for both assigned addresses to be approved in the relevant environment. Preserve access for other authorized backends. Review the Brails allowlist instructions before changing the list.

Step 1: install the helper without exposing a new endpoint

Create the shared directory if your project does not already have it. Copy the packet’s helper to:

supabase/functions/_shared/brails-check.mjs

Import it in the existing operator-only function:

import { checkBrailsSandbox } from "../_shared/brails-check.mjs";

Keep the helper as a module. It contains no public HTTP handler and makes no request on import. Your existing operator path remains responsible for authentication and authorization before calling it.

Step 2: set server configuration

In the relevant project’s Edge Function Secrets, set:

QUOTAGUARD_PROXY_URL = complete HTTP or HTTPS dashboard proxy URL
QUOTAGUARD_EXPECTED_IPS = first assigned IPv4,second assigned IPv4
BRAILS_SANDBOX_API_KEY = existing authorized sandbox key

The last value is unnecessary for echo mode. These lines show the required fields, not values to paste verbatim. Follow Supabase’s secrets documentation for your deployment environment. Do not put the values in frontend variables or commit a populated environment file.

Use the actual connection URL unchanged. The helper requires two distinct IPv4 entries and accepts only standard QuotaGuard proxy hostnames. A custom proxy domain needs a deliberate code review; it is not a reason to remove validation casually.

Step 3: check routing from the deployment

After the existing operator authorization checks have passed, invoke:

const routing = await checkBrailsSandbox("echo");

Keep the result private. It should contain an echoEgressIp equal to one of the configured addresses. The helper rejects unexpected addresses and does not proceed through a direct connection.

Run this from the actual deployed function and selected proxy protocol. A laptop test or a local mocked test covers a different environment.

Step 4: perform the sandbox read only when authorized

With permission to read the account, invoke:

const result = await checkBrailsSandbox("wallets");
if (!result.brailsHttpOk) {
  // Handle the sanitized status in the existing private operator workflow.
  // Do not return account diagnostics to an unauthenticated caller.
}

The helper calls the fixed Brails sandbox wallet endpoint after another successful echo. The result contains echoEgressIp, brailsStatus and brailsHttpOk. Wallet data is discarded.

The call requires exception handling as well as the boolean check. An invalid configuration or transport problem throws a stage-only error. An HTTP response such as 401 is returned with brailsHttpOk: false.

Step 5: record the evidence accurately

Do not label an echo result as the source Brails necessarily saw. Both addresses may be used, and the destinations use different connections. A successful wallet read does not exercise payout processing.

Step 6: verify proxy settings in the production integration

Keep the helper sandbox-only. In the actual Brails integration, verify the transport used by every relevant call, preserve the production key/hostname pairing, and confirm the production allowlist independently. Leave incoming webhooks and unrelated Supabase traffic alone.

If a check fails, use the troubleshooting table before altering security settings. Preserve TLS validation and the approved source-IP control while investigating.

Optional: run the helper’s offline tests

These commands run locally from the downloaded examples root and do not contact any service:

node --check code/brails-check.mjs
node --test code/brails-check.offline.test.mjs
node --test code/brails-check.supplementary.test.mjs

The test runner supplies mocked Deno and fetch implementations. This is a useful first code check before an authorized operator validates the deployment’s real network path.

Download the reference examples · Integration overview