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:
   Subscription (Manage Plan) → 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	30	2,000
Agency	60	10,000
Enterprise	120	50,000

Every successful (2xx) response from the API includes rate-limit headers reporting your current per-minute window:

• X-RateLimit-Limit — your per-minute request cap
• X-RateLimit-Remaining — requests remaining in the current minute
• X-RateLimit-Reset — Unix timestamp (seconds) when the window resets

If your account's per-minute limit is explicitly configured as unlimited, these headers are omitted rather than sent with a misleading value.

If you exceed your limits, you will receive HTTP 429.

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.

---

Summary

• Use the x-api-key header for all requests.
• Keys are managed in: Subscription (Manage Plan) → API Keys.
• Always store keys in secure server‑side systems.
• Follow rotation and rate‑limit best practices.

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