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.

Admin API

curl -k "https://localhost:7443/apisix/admin/services/cors-service?gateway_group_id={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={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
      }
    }
  }'

ADC

adc.yaml

services:
  - name: cors-service
    upstream:
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
    routes:
      - name: cors-route
        uris:
          - /get
        plugins:
          cors:
            allow_origins: "*"
            allow_methods: "GET,POST,PUT,DELETE,OPTIONS"
            allow_headers: "*"
            max_age: 3600

adc sync -f adc.yaml

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.

Admin API

curl -k "https://localhost:7443/apisix/admin/services/credentialed-cors-service?gateway_group_id={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={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
      }
    }
  }'

ADC

adc.yaml

services:
  - name: credentialed-cors-service
    upstream:
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
    routes:
      - name: credentialed-cors-route
        uris:
          - /get
        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

adc sync -f adc.yaml

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

• Inject Faults — test your application resilience.
• Configure Proxy Mirror — duplicate traffic to a test environment.
• Configure Rate Limiting — protect your APIs from abuse.