magnus919_agent-skills/supabase/references/application-services.md

Application services

Read this when building or debugging Auth, Data API, Realtime, Storage, or Edge Functions behavior.

Client configuration

A normal client needs:

• The public Supabase URL.
• A publishable key (or legacy anon key).
• A user session when acting as an authenticated user.

A trusted backend may use a secret/service-role key for administrative work. Keep separate client instances and configuration paths so the privileged key cannot enter browser/mobile bundles, generated static assets, telemetry, or error reports.

Auth

Configure and verify:

• SITE_URL and allowed redirects.
• External Auth URL/issuer and OAuth callback path.
• SMTP sender, host, port, credentials, and production deliverability.
• Email confirmation/autoconfirm behavior appropriate to the environment.
• OAuth/SAML/SMS/MFA provider settings and provider-console callbacks.
• Token lifetime, signing/JWKS configuration, and rotation plan.

Local CLI Auth settings live in supabase/config.toml; use env(NAME) for secrets and restart the local stack after changes. Self-hosted settings are environment variables passed to the Auth container and require container recreation to pick up changed environment.

Test the lifecycle through the gateway: create/invite or sign up, confirm as configured, sign in, refresh, inspect user, sign out/revoke, and reject invalid redirects. Do not infer email delivery from a successful Auth API response.

REST and GraphQL

PostgREST maps exposed schemas to HTTP APIs. Verify:

• Schema is intentionally in PGRST_DB_SCHEMAS.
• Grants match each API role.
• RLS is enabled and policies cover each operation.
• Expected maximum-row behavior and query filters.
• RPC functions use safe ownership and search_path.

The OpenAPI root /rest/v1/ currently requires an administrative key in the self-hosted release; a public key returning 403 there is not proof that table routes are broken. Test a real table route with the intended role.

GraphQL depends on pg_graphql. It is disabled by default on fresh Postgres 17 self-hosted deployments. An endpoint may return HTTP 200 with an error explaining that the extension is disabled, so inspect the JSON body as well as status.

Realtime

Realtime readiness requires more than an HTTP route. Verify:

1. The target table is included in the relevant publication/configuration.
2. The client connects through the gateway's WebSocket route with a valid API key.
3. RLS permits the subscribing user to observe the relevant rows.
4. A committed database change produces the expected event.
5. Reconnect and token refresh behavior work through the reverse proxy.

Reverse proxies must forward Upgrade/Connection behavior and X-Forwarded-* headers. Avoid exposing Realtime tenant-management routes; current official gateway configuration blocks sensitive paths.

Storage

Storage authorization is database-backed. Define buckets and object policies explicitly. For local reproducibility, bucket definitions and seed objects can be declared in supabase/config.toml and loaded with supabase seed buckets.

Test a complete object lifecycle with the intended role:

• Create or access the bucket.
• Upload within size/MIME constraints.
• Download and verify bytes or checksum.
• Generate/fetch a signed URL when required.
• Deny cross-user object access.
• Delete object and bucket/test fixture.

Self-hosted default file storage persists under the deployment's storage volume/bind path. S3-compatible backends require a separate override and backend-specific backup/availability controls. Database backup alone does not contain object bytes.

Edge Functions

CLI local/platform

Create and serve through the CLI local project before platform deployment:

supabase functions new FUNCTION_NAME
supabase functions serve
supabase functions deploy FUNCTION_NAME

Test the function's authorization, CORS, error path, and dependency behavior through the local gateway. Keep function secrets in the supported secrets mechanism, not source or config.toml literals. Platform deployment and secret/config updates target the linked managed project; verify the project reference first.

Self-hosted Docker

Functions live under volumes/functions/<name>/index.ts. The official stack's main worker loads functions from the mounted directory. Restart Functions after code changes; recreate it after changing environment/secrets:

sh run.sh restart functions
sh run.sh recreate functions

Invoke through the gateway:

curl http://localhost:8000/functions/v1/hello

The current self-hosted FUNCTIONS_VERIFY_JWT setting applies globally to Functions, not per function. Design explicit authorization inside functions that need different policies; do not assume platform deployment options map one-for-one to the self-hosted runtime.

Cross-service verification

A representative end-to-end flow should sign in a user, perform an RLS-protected REST operation, receive a Realtime event, upload/download a Storage object under policy, and invoke a Function through the gateway. Administrative setup/cleanup may use the secret key, but each user-facing assertion must use the same credentials and route as the application.