Configuring CORS

Learn how to manage Cross-Origin Resource Sharing (CORS) to secure your API against unauthorized external requests.

Overview

Cross-Origin Resource Sharing (CORS) is a security feature implemented by browsers. It prevents a website from making requests to a different domain than the one that served it, unless the server explicitly allows it.

In this guide, you will learn:

What CORS is and why it matters.
How JopiJS handles CORS by default.
How to authorize specific external domains to access your API.

1. What is CORS?

By default, web browsers follow the Same-Origin Policy (SOP). This means if your frontend is at https://myapp.com, it cannot fetch data from https://api.another-site.com unless that API says "I trust myapp.com".

CORS is the mechanism that allows servers to say "Yes, I allow this specific origin to access my data".

2. JopiJS Default Behavior

Zero Configuration: JopiJS enables CORS protection by default.
You don't have to do anything to secure your application.

By default, JopiJS only allows requests from the same origin (your own website). If you try to call your API from a different domain (like in a mobile app or a separate frontend), the browser will block the request.

3. Authorizing External Domains

If you need to allow other websites to access your JopiJS API, you can configure the allowed hosts in your application's entry point (src/index.ts).

Example Configuration

src/index.ts

import { jopiApp } from "jopijs";

jopiApp.startApp(import.meta, webSite => {
    // Begin CORS configuration
    webSite.configure_cors()
       .add_allowedHost("https://my-partner-app.com")
       .add_allowedHost("https://demo.example.org")
    .DONE_configure_cors(); // Finish configuration
});

How it works:

add_allowedHost(url): Adds a specific origin to the whitelist.
DONE_configure_cors(): Closes the configuration block and returns to the server builder.

4. CORS is a Browser-Only Protection

It is important to understand that CORS is not a server-side security layer for your API; it is a contract between the server and the browser.

Server-to-Server Calls:
JopiJS does not (and cannot) verify the origin of calls made directly from another server (e.g., using curl, Postman, or a backend script). Since the Origin header can be easily falsified in these environments, CORS protection is ineffective there.

This type of protection is specifically designed to protect users browsing the web from malicious scripts running in their own browsers. If you need to secure your API against other servers, you should use other mechanisms like API Keys, OAuth, or IP Whitelisting.

Summary of CORS Methods

Method	Description
`configure_cors()`	Opens the CORS configuration builder.
`add_allowedHost(url)`	Authorizes an external domain (e.g., `https://my-app.com`).
`DONE_configure_cors()`	Saves the settings and returns to the main server config.

Security Tip: Never allow all origins (*) in production unless your API is truly public and contains no sensitive user data. Always prefer whitelisting specific, trusted domains.

Configuring CORS

On this page