External Frontend Handoff

Share the exact Spala project contract a frontend developer or AI coding agent needs when they do not have dashboard access.

External Frontend Handoff

Use this page when a React, Next.js, mobile, Webflow, or AI-built frontend needs to connect to a Spala backend but the frontend developer does not have dashboard access.

The public docs explain the stable Spala integration rules. A specific frontend still needs the generated project contract from the project owner.

Owner action required

The project owner or builder should copy this packet from Lite Mode, Project Overview, Settings → API Docs, Settings → Security, Endpoints, and Channels before handing the work to an external frontend developer or AI coding agent.

OpenAPI is not the whole frontend contract

OpenAPI and generated SDK files cover REST routes. They may not include realtime channel protocol, storage-provider CORS, signed-upload PUT headers, cookie/CSRF details, refresh/logout behavior, or mobile callback rules unless those details are separately documented in the project handoff.

Copyable handoff packet

# Spala frontend handoff

Project name:
Environment: preview | production
Published backend API: yes | no

API_BASE_URL=
OpenAPI JSON file or URL=
Generated SDK file or URL=
Markdown API docs file or URL=

Auth:
- Login route:
- Signup/register route:
- Token response field:
- Protected request header: Authorization: Bearer USER_JWT
- Token lifetime / refresh behavior:
- Session mode: bearer token | refresh token | cookie session | custom
- Cookie credential mode, if used: include | same-origin | none
- CSRF requirement, if cookie session is used:
- Logout behavior:

Routes:
- List the main /api/... routes or attach the generated API Docs export.

Errors:
- HTTP status codes used by each route:
- Error response JSON shape:
- Validation error shape:
- Auth error shape:
- Request id / trace id field, if exposed:

Files/uploads:
- Upload mode: multipart | signed URL | addon-backed storage | none
- Upload route:
- Max file size:
- Returned file object shape:

Realtime:
- WebSocket URL or path:
- Auth mode: query token | cookie | subprotocol | API key | project-specific handshake | none
- Subscribe message envelope:
- Event payload examples:
- Heartbeat interval / pong timeout:
- Close codes:
- Replay or no replay:
- Permissions/channel access:
- Reconnect expectations:

CORS:
- Frontend origin:
- Origin added in Settings → Security → CORS Allowed Origins: yes | no
- Backend API republished after CORS/settings change: yes | no
- Credentials required by browser requests: yes | no
- Expected preflight headers:

Public docs:
- Public /api/docs enabled: yes | no
- If no, attach private Markdown/OpenAPI/SDK exports.

Minimum viable handoff

At minimum, provide these four items:

1. The exact API_BASE_URL copied from Lite Mode or Project Overview.
2. The generated OpenAPI JSON, Markdown docs, or TypeScript SDK from Settings → API Docs.
3. The auth route and token response shape.
4. Confirmation that the frontend origin is allowed in Settings → Security → CORS Allowed Origins.

Without those, an external frontend developer can understand Spala but cannot safely wire a real private project.

If the project uses uploads, realtime, cookies, CSRF, refresh tokens, OAuth callbacks, or direct-to-storage signed URLs, the owner must also include those contracts. Do not assume OpenAPI or the generated SDK fully describes them.

Auth/session fields to include

Generated Spala projects commonly use bearer JWT auth, but projects can define different session behavior. Include the exact variant used by the project:

| Session field | What the frontend needs |
| --- | --- |
| Login and signup routes | Exact /api/... paths and request bodies from generated API Docs |
| Token field | Exact JSON field such as token, accessToken, or data.token |
| Refresh behavior | Whether refresh exists, the refresh route, expiry, and retry rules |
| Cookie sessions | Whether requests need credentials: "include" and whether CSRF headers are required |
| Logout | Whether logout is local token clear, server-side session revoke, or both |
| Error semantics | Expected 401 and 403 behavior |

If the project uses cookies, include the cookie mode and CSRF header names. If it uses bearer tokens, include the token lifetime and storage expectation. Public Spala docs describe the patterns; the generated project docs are the source of truth.

REST error fields to include

REST error handling is route-specific. A public documentation page cannot provide a private project's actual error response bodies. Before a frontend developer or AI agent wires error handling, the project owner should copy the status codes and error JSON examples from generated API Docs, OpenAPI, SDK types, or API Playground.

At minimum, include:

| Error field | What the frontend needs |
| --- | --- |
| Status codes | Expected 400, 401, 403, 404, 409, 422, and 500 cases for each route, as applicable |
| Error body shape | Exact JSON body returned by the route, such as message, code, details, fieldErrors, or project-specific fields |
| Validation errors | Field-level validation format and how arrays/nested objects are reported |
| Auth errors | Token-expired, missing-token, invalid-token, and insufficient-permission behavior |
| Request trace | Request id, trace id, or log correlation field if the project exposes one |

Do not assume one universal error schema across all Spala projects. If a route's error response is not shown in generated docs, test the route in API Playground before wiring frontend error handling.

CORS fields to include

For browser frontends, include the exact deployed frontend origin, not a wildcard or partial host:

Frontend origin: https://app.example.com
Methods used: GET, POST, PUT, PATCH, DELETE
Request headers: Content-Type, Authorization
Credentials: true | false

The origin must match the browser page origin, including scheme, host, and port. After changing Settings → Security → CORS Allowed Origins, publish the backend API again before asking the frontend developer to retest.

Use CORS and Security for the exact owner checklist.

Example SDK handoff

If Settings → API Docs generated a TypeScript SDK, attach it or share the authenticated download route. A minimal generated SDK normally exposes the base URL, typed request helpers, and route functions similar to this:

export type SpalaClientOptions = {
  baseUrl: string;
  token?: string;
};

export function createSpalaClient(options: SpalaClientOptions) {
  async function request<T>(path: string, init: RequestInit = {}): Promise<T> {
    const response = await fetch(`${options.baseUrl}${path}`, {
      ...init,
      headers: {
        "Content-Type": "application/json",
        ...(options.token ? { Authorization: `Bearer ${options.token}` } : {}),
        ...init.headers,
      },
    });

if (!response.ok) {
      throw new Error(`Spala API error ${response.status}`);
    }

return response.json() as Promise<T>;
  }

return {
    listCases: () => request<Array<{ id: string; title: string }>>("/api/cases"),
  };
}

This snippet shows the expected shape only. Use the project-generated sdk.ts for real route names and types.

Realtime fields to include

If the project uses realtime channels, the owner should copy the contract from Channels and the generated project docs into this handoff. There is no safe public-docs default for a private project's realtime protocol.

Owner workflow:

1. Open the project in the dashboard.
2. Open Channels and select the channel used by the frontend.
3. Copy the exact WebSocket path or URL, auth mode, allowed audience, and permissions.
4. Copy subscribe, event, error, heartbeat, close-code, replay, and reconnect examples from the channel configuration or generated project docs.
5. Add those examples to the handoff packet before assigning frontend work.

Include a complete message sample:

{
  "connectUrl": "wss://PROJECT_HOST/ws?token=USER_JWT",
  "subscribe": { "type": "subscribe", "channel": "cases" },
  "event": {
    "type": "case.updated",
    "channel": "cases",
    "payload": { "id": "case_123", "status": "open" }
  },
  "error": { "type": "error", "code": "unauthorized", "message": "Invalid token" }
}

Also state whether replay, presence, acknowledgements, or reconnect backoff are implemented. If the project does not define those behaviors, the frontend should treat realtime as best-effort live updates and fetch REST state after reconnect.

No dashboard access workflow

1. Project owner publishes or previews the backend API.
2. Project owner exports API Docs from Settings → API Docs.
3. Project owner copies the API base URL from Lite Mode or Project Overview.
4. Project owner copies realtime, upload, cookie/CSRF, refresh/logout, and mobile callback details when the project uses them.
5. Project owner adds the frontend origin in Settings → Security.
6. Project owner republishes the backend API after CORS/security changes.
7. Project owner sends the handoff packet and generated docs to the frontend developer.
8. Frontend developer stores the base URL in VITE_SPALA_API_BASE_URL or NEXT_PUBLIC_SPALA_API_BASE_URL.
9. Frontend developer tests one public route, one auth route, and one protected route before building the full UI.

Verification commands

Replace the placeholders with project values.

curl "$API_BASE_URL/api/health"

curl -X POST "$API_BASE_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  --data '{"email":"[email protected]","password":"example"}'

curl "$API_BASE_URL/api/me" \
  -H "Authorization: Bearer USER_JWT"

If browser calls fail but curl works, check CORS first. The frontend origin must match exactly, including scheme and port, and published settings must be live.

Handoff quality checklist

- API_BASE_URL is exact and includes any required scoped path.
- OpenAPI, Markdown docs, or SDK matches the currently published API.
- Auth token response is documented with the exact field name.
- Route-specific error response shapes are documented or verified in API Playground.
- Upload and realtime contracts are included when those features are used.
- CORS origin is configured before browser integration starts.
- Public docs are intentionally enabled, or private docs exports are attached.
- The frontend developer knows whether they are targeting preview or production.

Frontend Integration Cookbook
/guides/frontend-integration
Stable frontend request, auth, upload, realtime, and CORS patterns
API Docs
/features/api-docs
Export generated project contracts
CORS and Security
/settings/cors-security
Add frontend origins and publish security changes
Publish
/features/publish-export
Publish backend API changes before external integrations depend on them