Skip to main content
API7.ai Logo
Version: 3.9.x

Configure CORS

Cross-Origin Resource Sharing (CORS) is a security mechanism that allows web browsers to make requests to a domain different from the one that served the original web page. The cors plugin simplifies this by handling the necessary headers on the Gateway.

Use this guide for the common CORS workflows. For the full plugin field reference, regex matching, and plugin metadata options, see cors.

Prerequisites​

  • An API7 Enterprise instance is running.
  • A Gateway Group is created and a Gateway instance is running.
  • A token from the Dashboard.

Configure Basic CORS​

The following configuration allows requests from any origin with default methods and headers.

curl -k "https://localhost:7443/apisix/admin/services/cors-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cors-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/cors-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cors-route",
    "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    "paths": ["/get"],
    "service_id": "cors-service",
    "plugins": {
      "cors": {
        "allow_origins": "*",
        "allow_methods": "GET,POST,PUT,DELETE,OPTIONS",
        "allow_headers": "*",
        "max_age": 3600
      }
    }
  }'

Configure Secure CORS with Credentials​

To allow credentials such as cookies or authorization headers, you must specify the allowed origins and set allow_credential to true.

curl -k "https://localhost:7443/apisix/admin/services/credentialed-cors-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "credentialed-cors-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/credentialed-cors-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "credentialed-cors-route",
    "methods": ["GET", "POST", "OPTIONS"],
    "paths": ["/get"],
    "service_id": "credentialed-cors-service",
    "plugins": {
      "cors": {
        "allow_origins": "https://example.com,https://api.example.com",
        "allow_methods": "GET,POST",
        "allow_credential": true,
        "expose_headers": "X-Custom-Header",
        "max_age": 600
      }
    }
  }'

Validate the Configuration​

You can simulate a CORS preflight request using curl:

curl -i -X OPTIONS "http://127.0.0.1:9080/get" \
  -H "Origin: https://example.com" \
  -H "Access-Control-Request-Method: POST"

The response should include headers such as Access-Control-Allow-Origin and Access-Control-Allow-Methods based on your configuration.

If the route returns 404 immediately after you apply the configuration, wait a few seconds for the latest configuration to reach the gateway and retry.

Next Steps​