Skip to main content

CORS Origins

Use CORS origins to control which browser origins can create Imgwire standard uploads with Client API Keys.

Overview​

CORS origins apply to browser requests against POST /api/v1/images/standard_upload when the request uses a Client Key. They are useful when your frontend uploads directly to Imgwire and you want browsers to accept responses only for known application origins.

If an Environment has no CORS origins configured, any browser origin can attempt upload creation with a valid Client Key for that Environment. Add CORS origins before using Client Keys from production browser apps.

How matching works​

Imgwire compares the incoming browser Origin header to the CORS origin patterns configured for the Environment.

Use the pattern field to store the allowed host pattern:

PatternExample matching Origin
app.example.comhttps://app.example.com
uploads.example.comhttps://uploads.example.com
*.example.comhttps://app.example.com or https://uploads.example.com
localhost:3000http://localhost:3000

The pattern is host-oriented. Do not include a path. Include a port when the browser origin includes a non-default local development port.

When at least one CORS origin is configured, non-matching browser origins do not receive the CORS response headers needed for browser access. The browser blocks the response even if the API request itself can be processed.

Endpoints​

MethodPathPurpose
GET/api/v1/cors_origins/List CORS origins
POST/api/v1/cors_origins/Create a CORS origin
GET/api/v1/cors_origins/{cors_origin_id}Retrieve a CORS origin
PATCH/api/v1/cors_origins/{cors_origin_id}Update a CORS origin
DELETE/api/v1/cors_origins/{cors_origin_id}Delete a CORS origin

For programmatic backend integrations, manage CORS origins with a Server API Key.

Create a CORS origin​

curl https://api.imgwire.dev/api/v1/cors_origins/ \
  -X POST \
  -H "Authorization: Bearer $IMGWIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pattern":"app.example.com"}'

Example response:

{
  "id": "75d9d76e-7f28-472f-8012-786e579eca39",
  "environment_id": "26f80c13-48bd-4bb9-866e-5e9392b11a6a",
  "pattern": "app.example.com",
  "created_at": "2026-05-09T18:30:00Z",
  "updated_at": "2026-05-09T18:30:00Z"
}

List CORS origins​

curl "https://api.imgwire.dev/api/v1/cors_origins/?page=1&limit=20" \
  -H "Authorization: Bearer $IMGWIRE_API_KEY"

The response body is an array of CORS origin records. Pagination metadata is returned in X-Total-Count, X-Page, X-Limit, X-Prev-Page, and X-Next-Page headers.

Best practices​

  • Add your production frontend host before shipping direct browser uploads with Client Keys.
  • Add local development origins such as localhost:3000 only when they are needed.
  • Use exact host patterns for production apps when possible.
  • Use wildcard patterns such as *.example.com only when multiple subdomains need upload access.
  • Treat CORS as browser access control, not authentication. Use signed uploads when your backend should decide who may upload.

Common mistakes​

  • Assuming CORS protects mobile apps, backend scripts, or other non-browser clients.
  • Leaving the Environment without CORS origins and expecting Client Key uploads to be browser-origin restricted.
  • Including URL paths in pattern; CORS origin matching is based on the origin host, not request paths.
  • Forgetting that signed upload Client Keys still need your backend to issue upload tokens.

Last updated at: May 9, 2026