voyageai-cli

# CORS (Cross-Origin Resource Sharing) CORS allows browser-based JavaScript applications to make requests to the API from different origins (domains). Understanding CORS configuration is essential for web application integrations. ## CORS Basics When a browser loads a page from `https://app.example.com` and that page's JavaScript makes a request to `https://api.example.com`, the browser enforces the Same-Origin Policy for security. The API must explicitly allow cross-origin requests via CORS headers. The browser automatically includes an `Origin` header in cross-origin requests: ``` Origin: https://app.example.com ``` The API responds with CORS headers: ``` Access-Control-Allow-Origin: https://app.example.com Access-Control-Allow-Methods: GET, POST, OPTIONS ``` If the origin is allowed, the browser permits the response. Otherwise, the response is blocked. ## Allowed Origins Configure allowed origins in the API dashboard under Settings → CORS. ``` Allowed Origins: https://app.example.com https://www.example.com https://localhost:3000 (for local development) https://*.example.com (wildcard subdomains) ``` Only requests from allowed origins succeed. Requests from other origins are rejected. ## Preflight Requests For requests with custom headers (e.g., `Authorization`) or non-simple methods (POST, PATCH, DELETE), browsers send an automatic OPTIONS preflight request: ``` OPTIONS /users Origin: https://app.example.com Access-Control-Request-Method: POST Access-Control-Request-Headers: Authorization, Content-Type ``` The API must respond with CORS headers: ``` 200 OK Access-Control-Allow-Origin: https://app.example.com Access-Control-Allow-Methods: GET, POST, PATCH, DELETE Access-Control-Allow-Headers: Authorization, Content-Type Access-Control-Max-Age: 86400 ``` **Access-Control-Max-Age**: How long the browser caches the preflight response (in seconds). Set to 86400 (24 hours) to reduce preflight overhead. ## Simple Requests GET and POST requests with simple headers don't require preflight: ``` GET /users Origin: https://app.example.com Response: 200 OK Access-Control-Allow-Origin: https://app.example.com ``` Simple headers: `Content-Type` (with specific values), `Accept`, `Accept-Language`. ## Credentials (Cookies, Authorization) By default, cookies and authorization headers aren't sent in cross-origin requests for security. To include them: Client-side (JavaScript): ```javascript fetch('https://api.example.com/users', { credentials: 'include', // Include cookies and auth headers: {'Authorization': 'Bearer ...'} }) ``` Server-side (API): ``` Access-Control-Allow-Credentials: true Access-Control-Allow-Origin: https://app.example.com (must be specific, not *) ``` Note: When using `Access-Control-Allow-Credentials: true`, you cannot use `Access-Control-Allow-Origin: *`. Origins must be explicitly listed. ## Common CORS Errors **"No 'Access-Control-Allow-Origin' header"**: The origin isn't in the allowed list. Add it to CORS settings. **"Credentials mode is 'include' but 'Access-Control-Allow-Credentials' is missing"**: The API doesn't allow credentials. Set `Access-Control-Allow-Credentials: true` or remove client-side `credentials: 'include'`. **"Method not allowed"**: The HTTP method (POST, PATCH, etc.) isn't in `Access-Control-Allow-Methods`. Add it to CORS configuration. **"Header not allowed"**: Custom headers aren't in `Access-Control-Allow-Headers`. Add them to CORS settings. ## Wildcard Origins Using `Access-Control-Allow-Origin: *` makes the API accessible from any origin. This is convenient for public APIs but reduces security. Use wildcards only for public endpoints that don't require authentication. For authenticated APIs, explicitly list allowed origins. ## Development vs. Production **Development**: Allow `https://localhost:3000`, `https://localhost:8080`, etc. **Production**: Explicitly list production domains only (e.g., `https://app.example.com`). Never use `*` in production for authenticated endpoints. ## CORS in Single-Page Applications SPAs are particularly affected by CORS. When deploying an SPA to a CDN, the CDN origin must be in the API's allowed list: ``` SPA deployed to: https://cdn.example.com/app/ API at: https://api.example.com/ CORS setting: Allowed Origins: https://cdn.example.com ``` ## Testing CORS Test CORS with curl: ```bash curl -i -X OPTIONS https://api.example.com/users \ -H "Origin: https://app.example.com" \ -H "Access-Control-Request-Method: POST" ``` Check response headers for CORS directives. ## CORS vs. Authentication CORS allows *which domains* can make requests. [Authentication](../auth/api-keys.md) determines *who* (which user) can access resources. Both are required for secure APIs. CORS without authentication: Any origin can make requests, but requires valid credentials. Authentication without CORS: Requests from any origin are rejected (unless same-origin).