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={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": ["/cors"],
    "service_id": "cors-service",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/get"
      },
      "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:
          - /cors
        methods:
          - GET
          - POST
          - PUT
          - DELETE
          - OPTIONS
        plugins:
          proxy-rewrite:
            uri: /get
          cors:
            allow_origins: "*"
            allow_methods: "GET,POST,PUT,DELETE,OPTIONS"
            allow_headers: "*"
            max_age: 3600
    labels:
      docs-example: cors-service

Preview the changes owned by this example and confirm that the diff contains no unintended updates or deletions:

adc diff -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=cors-service

Synchronize the reviewed configuration:

adc sync -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=cors-service

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={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": ["/credentialed-cors"],
    "service_id": "credentialed-cors-service",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/get"
      },
      "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:
          - /credentialed-cors
        methods:
          - GET
          - POST
          - OPTIONS
        plugins:
          proxy-rewrite:
            uri: /get
          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
    labels:
      docs-example: credentialed-cors-service

Preview the changes owned by this example and confirm that the diff contains no unintended updates or deletions:

adc diff -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=credentialed-cors-service

Synchronize the reviewed configuration:

adc sync -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=credentialed-cors-service

Validate the Configuration

Verify the wildcard policy with a preflight request:

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

Then verify the credentialed policy on its separate route:

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

Each response should include the Access-Control-Allow-Origin and Access-Control-Allow-Methods values from its route. The credentialed route should also return Access-Control-Allow-Credentials: true.

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.