CORS and Security

Configure frontend origins, credentialed browser requests, trusted hosts, and publish requirements for Spala project APIs.

CORS and Security

Use this page when a browser frontend, mobile app, or external UI needs to call a Spala project API.

Owner Checklist

1. Open the project in the hosted dashboard.
2. Go to Settings → Security.
3. Add the exact frontend origin in CORS Allowed Origins.
4. Include the scheme, host, and port, such as https://app.example.com or http://localhost:5173.
5. Do not include URL paths.
6. Allow the request headers the frontend sends, usually Authorization and Content-Type.
7. Enable credentialed requests only when the project intentionally uses cookie sessions.
8. Save the settings.
9. Publish the backend API before asking the frontend developer to retest.

Publish after security changes

Saved CORS/security settings do not help the live API until the project is published. If curl works but browser requests fail, confirm the origin is exact and the latest settings are published.

Browser Rules

Browser CORS uses the page origin, not the API route:

https://app.example.com
http://localhost:5173

Do not add paths such as https://app.example.com/dashboard.

If the frontend sends a bearer token, allow Authorization. If it sends JSON, allow Content-Type. If it uses cookies, the response must use the exact origin, not *, and must include credential support.

Cookie Sessions

Cookie sessions need a tighter contract than bearer tokens. Include these fields in the frontend handoff:

| Field | What to specify |
| --- | --- |
| Credential mode | include, same-origin, or none |
| Cookie SameSite | Lax, Strict, or None |
| Cookie Secure | Required for cross-site HTTPS cookies |
| Domain/path | Which frontend and API hosts receive the cookie |
| CSRF | Header name and source, or not required |
| Logout | Local clear, server revoke, cookie expiry, or a combination |

Verification

After publishing, test one preflight-shaped browser request and one real request from the frontend origin.

OPTIONS /api/cases HTTP/1.1
Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: authorization, content-type

Expected shape:

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type

For credentialed requests:

Access-Control-Allow-Credentials: true

Handoff Fields

Add these fields to External Frontend Handoff:

- Frontend origin
- Whether the origin is saved in Settings → Security
- Whether the backend was republished after the change
- Required request headers
- Whether credentials are enabled
- Cookie and CSRF details if used

External Frontend Handoff
/guides/frontend-handoff
Copy the complete frontend packet
Frontend Integration Cookbook
/guides/frontend-integration
Use CORS with auth, uploads, and realtime
Publish
/features/publish-export
Publish security changes to the live API
API Docs
/features/api-docs
Share REST contracts with frontend builders