Secrets and backends

Everything in a Shell app runs in your users' browsers, and anyone can read its code. So a Shell app must never hold a secret: no API keys, no passwords, no AI model keys. Work that needs a secret, or must run on a server, goes in a backend: a Coderunner that your app calls.

When you need a backend

• Calling a service that needs an API key: payments, email, a third-party API.
• Calling AI models through the LLM Gateway (coming soon), which needs your workspace's key.
• Logic users mustn't be able to see or change: pricing, approvals, anything that checks permissions itself.

Reading and writing your own data, files and flags doesn't need a backend: your app does that directly with the user's token.

Build the backend

1. Deploy a Service with an HTTP API: your own server, in any language.
2. Store its secrets in Data → Secrets, and have it read them at runtime with an M2M token. See Configuration and secrets.
3. Call it from your app, passing the signed-in user's token. Use the backend's own domain if you've given it one (see Domains), otherwise its Deployment URL:

const res = await fetch("https://api.example.com/api/checkout", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${await window.__GF_GET_ACCESS_TOKEN__()}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ planId }),
});

Your Shell site and the backend are on different addresses, so the browser blocks this call unless the backend allows your Shell site's address (CORS). See Allow calls from your Shell site.

4. In the backend, check the token on every request: anyone can call a Service directly, signed in or not. Who can reach your Service shows what to check, where the user's roles are, and examples for FastAPI and Node.js.

The backend calls Groundfloor with its own M2M token, not the user's, so it can only do what you've allowed that M2M client to do.

AI models

Call AI models from the backend, not the app. Once the LLM Gateway is available (it's coming soon), store your workspace's LLM Gateway key in Secrets as LITELLM_API_KEY, read it at runtime, and send requests to the gateway with any OpenAI-compatible client. See LLM Gateway for the key and the available models.

Next steps

• Services — deploy the backend.
• M2M tokens — credentials for the backend.
• Secrets — store and rotate secrets.