Configure CORS

Learn how to configure Cross-Origin Resource Sharing (CORS) for your APIs to allow or restrict access from different domains.

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
      }
    }
  }'

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.

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
      }
    }
  }'

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.