CorsAPI istifadə təlimatı — tətbiqiniz və infrastruktur üçün

CorsAPI sits between your frontend (or any HTTP client) and third-party HTTP APIs. It applies CORS rules you define, validates the target URL against host and path allowlists, attaches your identity using an API key, and enforces per-minute quotas. It is not an open relay: only hosts and paths you explicitly allow can be reached, which is essential for security and compliance.

You host the backend and database yourself. The dashboard is where you create projects, paste browser origins, list upstream hosts (optionally with wildcards), narrow path prefixes, and issue API keys. The same concepts apply whether you use curl from a server, fetch from React, or a mobile WebView—only browser calls require correct Origin and CORS headers.

After you register, you work inside the dashboard. A project is the unit that owns proxy rules, API keys, and quota counters. Organizations are optional but useful when several people share workspaces and roles. For a solo developer, one project is enough to start; you can add staging vs production as separate projects later if you want isolated keys and limits.

Every proxied request is attributed to a project via the API key you send. Rotating a key in the dashboard invalidates the old secret immediately for new requests, so plan key rotation with a short overlap if you run zero-downtime deploys.

After sign-in you open the workspace and select a project. In one place you maintain: allowed browser origins, upstream host rules, optional path prefixes, per-minute rate limit, and API keys. When something fails, change one variable at a time—if the browser shows a CORS error, verify origins first; if the proxy returns 400, verify host/path rules and URL encoding before blaming the upstream vendor.

Create separate named keys per environment (for example development versus production) so you can revoke one without taking down the other. Usage summaries help you see whether traffic spikes come from one key or one upstream. Treat keys like passwords: never paste them into public tickets or shared documents; rotate immediately if a secret might have leaked.

Your project settings are the contract between your application and the proxy: keep a short internal note of which hosts and paths are approved for each release, and review them when a vendor changes base URLs or deprecates routes.

Browsers send an Origin header on cross-origin XHR/fetch. CorsAPI compares that value to the origin list in your project. Each line should be a full origin: scheme + host + port, for example http://localhost:5173 or https://app.example.com. Trailing slashes are not needed; be consistent with http vs https because they are different origins.

Local development often uses several ports (frontend on 3000, API tool on 5173). Add every port you use. Preview deployments from Vercel or Netlify get unique subdomains—add them when you test, or use a stable preview URL pattern if your team shares one. If an origin is missing, the browser will show a CORS error even when the proxy itself would allow the upstream.

Host rules describe which DNS names your proxy may call. Examples: api.stripe.com, api.github.com. Subdomain wildcards like *.example.com match any single level (api.example.com matches; a.b.example.com does not). Be as narrow as possible: allow only the APIs you integrate, not generic patterns that widen over time without review.

If a host is not allowed, the proxy rejects the request before it leaves your network. That protects you from accidental open-proxy behavior and from typos in client code that would otherwise hit unexpected domains.

If you leave path rules empty for a host, any path on that host is permitted within your other limits. If you set prefixes—such as /v1/ or /repos—only URLs whose path starts with one of those prefixes are allowed. This is useful when a large API surface exists but your product only needs a few routes.

Combine host + path when different microservices share a domain behind a gateway: you can allow /payments/* to one behavior and /public/* to another by splitting projects or by careful prefix design. When in doubt, start restrictive and relax after you see real traffic patterns in logs.

Each project has at least one secret key. Send it on every proxy request as X-CorsAPI-Key: <secret> or Authorization: Bearer <secret>. The backend validates the key, loads the project rules, then forwards to the upstream URL you passed in the query string (or equivalent API shape—see OpenAPI for exact parameters).

Server-side calls should prefer environment variables for the key so it never appears in frontend bundles. Browser calls need a key that the browser can read—which means treat that project as a public client surface: tighten hosts, paths, and quotas aggressively, and never point at internal admin APIs through the same key.

Use curl to verify connectivity before you debug fetch. Replace YOUR_SECRET with a key from the dashboard and encode the target URL. A 200 response with body from the upstream confirms host/path rules, key validity, and network reachability. If you get 401, the key is wrong or revoked; 400 often means URL encoding or allowlist mismatch.

Keep curl examples in your runbooks so on-call engineers can reproduce issues without the frontend build pipeline.

From your SPA, call the CorsAPI base URL your team configured for that environment (for example the same host as your app’s API, or a dedicated subdomain) with the proxy path and your key headers. The browser must run on an origin listed in the project. Use mode: 'cors' and expect CorsAPI to emit Access-Control-* headers matching your origin list.

If you use cookies for your own app session, do not confuse them with the CorsAPI key: the key identifies the proxy project, while your session cookie is unrelated unless you explicitly integrate them.

In Node, Deno, or serverless handlers, store the key in secrets and call the proxy the same way as curl. This pattern is ideal for cron jobs, webhooks that fan out to third parties, or when the upstream should only see your datacenter IPs. You still benefit from centralized quotas and auditability in one project.

When scaling horizontally, remember quotas are per project key: many instances share the same minute window; design limits so bursts do not exhaust the window for all consumers.

Any product that can send HTTP with custom headers can use the proxy—REST clients, low-code automation, scheduled jobs, or native mobile stacks. Point the tool at your CorsAPI base URL, use the proxy path and parameters described in the published API reference, pass the target upstream URL as required, and send X-CorsAPI-Key or Authorization: Bearer with your project secret.

In desktop API testers (such as Postman or Insomnia), store the base URL and key in environment or collection variables so you do not retype secrets. Reproduce the same call with curl to see whether a problem is the tool, TLS, or the proxy rules.

Automation platforms that offer an HTTP request step let you set method, URL, and headers. Match the proxy URL exactly as in the examples; some UIs encode query strings automatically—avoid double-encoding. For cron-style jobs, respect per-minute quotas by spacing calls or batching work on your side.

Do not embed production secrets in public collections, shared snippets, or code you do not control. For demos, use a disposable project with minimal host scope and strict limits.

Successful proxy responses include rate-limit hints such as X-RateLimit-Limit and X-RateLimit-Remaining (names may match your deployment; see live responses). These reflect your project’s per-minute budget. Track them in the client to back off before hitting hard errors.

When the window is exhausted, you may receive HTTP 429 Too Many Requests. Implement exponential backoff and jitter for retries, and surface a clear UI state when the user hits product-level limits—not only network errors.

400: malformed proxy URL, validation failed, or host/path not allowed—fix configuration or encoding. 401: missing or invalid API key, or session invalid for dashboard routes. 429: quota exceeded—slow down or raise limits if your operator allows. 502/504: upstream failure or timeout—retry idempotent reads, avoid retry storms on writes.

Log correlation IDs if your deployment adds them, and compare with dashboard analytics to see whether errors cluster on one upstream or one project key.

Signing into the website stores session tokens in httpOnly cookies for the control plane. That session is separate from project API keys used by the proxy. Logging out clears the dashboard session; it does not rotate project keys unless you do so explicitly in settings.

For automation, prefer API keys and health checks rather than scraping the dashboard.

Use GET /api/health/live to know if the process responds, /api/health/ready when the database must be reachable, and /api/health for a fuller check. Wire these into Kubernetes readiness probes or load balancer checks so traffic drains before a bad deploy takes hold.

Do not expose detailed health data publicly without authentication if your threat model requires hiding infrastructure shape.

GET /api/plan/limits returns the active caps for the current free tier. Call it without authentication to show limits in internal tools or to sanity-check configuration after a deployment.

Interactive API documentation may be available under /api/docs when your deployment exposes it. In production, restrict that URL (for example network access or authentication) so the surface is not anonymously enumerable. Use the published schema to confirm parameter names for the proxy and related routes while you integrate.