Authentication

QRForge exposes a private, key‑based HTTP API. Every request must be authenticated using an API key associated with your QRForge account.
This page explains how API keys work, how to use them, and how QRForge enforces security for enterprise‑grade integrations.

---

Base URL

All authenticated API requests use the production API endpoint:

https://api.qrforge.link

All examples assume this base URL.

A dedicated sandbox environment will be introduced later.

---

API Key Types

QRForge uses prefix‑scoped keys to clearly indicate their purpose:

Type	Prefix	Description
Live secret key	api_live_	Full‑privilege key for production traffic

Characteristics:

• Secret keys must never be exposed in client‑side code.
• Keys are long‑lived and tied to your QRForge Workspace.
• Keys enforce plan limits, quotas, and permissions.
• Multiple keys per account are supported (per environment, team, or service).

---

Managing Your API Keys

You can view and manage API keys in the QRForge Dashboard:

1. Log in to https://app.qrforge.link
2. Navigate to:
   Settings → Developer → API keys
3. Create or revoke keys as needed.
4. Copy your key once and store it securely (it will be partially hidden afterwards).

Security Reminder:
Store keys in a secrets manager (GCP Secret Manager, AWS Secrets Manager, HashiCorp Vault, etc.).
Never commit them to Git repositories.

---

Sending Authenticated Requests

All requests require the x-api-key header:

x-api-key: api_live_xxxxxxxxxxxxxxxxxxxxx

Example — cURL

curl -X GET "https://api.qrforge.link/v1/qr-codes" \
  -H "x-api-key: api_live_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Example — Node.js (fetch)

const API_KEY = process.env.QRFORGE_API_KEY;

const response = await fetch("https://api.qrforge.link/v1/qr-codes", {
  method: "GET",
  headers: {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(data);

---

Authentication Errors

If authentication fails, you may receive:

Status	Meaning	Cause
401 Unauthorized	Invalid or missing API key	Header missing, malformed key, revoked key
403 Forbidden	Key is valid but lacks permission	Insufficient plan, blocked action
429 Too Many Requests	Rate limit exceeded	Too many requests for this key

All errors follow a consistent schema:

{
  "ok": false,
  "code": "unauthorized",
  "message": "Invalid or missing API key."
}

---

Rate Limiting

QRForge enforces rate limits per API key to ensure platform stability.

Plan	RPM	Daily quota
Pro	300	50,000
Agency	1,000	250,000
Enterprise	Custom	Custom

If you exceed your limits:

• You will receive HTTP 429
• Responses may include:
  X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

For higher throughput, contact support@qrforge.link.

---

Key Rotation (Best Practice)

Rotating keys regularly is essential for maintaining security and compliance.

Recommended workflow:

1. Create a new key.
2. Deploy it across all services.
3. Verify logs show usage of the new key.
4. Revoke the old key.

This allows zero‑downtime credential rotation.

---

Optional: IP Allow‑Listing

Enterprise accounts may request IP allow‑listing to restrict access to specific IP ranges.
This ensures only approved backend servers can call the API with your keys.

To request allow‑listing, contact your account manager.

---

Summary

• Use the x-api-key header for all requests.
• Keys are managed in: Settings → Developer → API keys.
• Always store keys in secure server‑side systems.
• Follow rotation and rate‑limit best practices.
• For advanced security, enterprise IP allow‑listing is available.

You may now continue to the next section: QR Codes API.