API Keys

Overview

GrowQR API Keys give you programmatic access to the platform so you can create links, retrieve analytics, manage campaigns, and configure resources without touching the dashboard. Every action available in the web UI is also available through the REST API, and API keys are how you authenticate those requests.

API keys are scoped to a specific workspace, carry configurable permission levels, and can be rotated or revoked at any time. Whether you're integrating GrowQR into a CI/CD pipeline, building a custom dashboard, or automating link creation from a CRM, API keys are the foundation.

What Problem It Solves

Teams that manage hundreds or thousands of links can't create them one at a time in a web interface. Marketing automation platforms, e-commerce systems, and content management tools need to generate short links on the fly — programmatically and at scale. Without an API, teams resort to manual work, CSV imports, or fragile browser automation scripts.

API keys solve this by providing a secure, stable authentication mechanism for the GrowQR API. Unlike session-based auth (which requires a browser and cookies), API keys work from any HTTP client — server-side scripts, Lambda functions, GitHub Actions, Zapier webhooks, or a simple curl command.

How It Works

When you create an API key, GrowQR generates a cryptographically random token tied to your workspace. Every API request must include this token so the server can:

1. Authenticate — Verify that the token is valid and hasn't been revoked.
2. Authorize — Check that the key's permission scope allows the requested action.
3. Scope — Ensure the request operates within the key's workspace boundary.

Dual Authentication

All API endpoints support both JWT tokens (from dashboard login) and API keys. This means:

• Dashboard users are authenticated via JWT automatically.
• External integrations, scripts, and CI/CD pipelines use API keys.
• Both methods enforce the same permission model, so a Read-only API key has the same restrictions as a Read-only role.

Permission Scopes

API keys support two permission scopes:

Authentication Methods

GrowQR accepts API keys in three ways. Use whichever method your HTTP client supports:

1. Authorization header (recommended):

curl -H "Authorization: Bearer growqr_live_abc123..." \
  https://api.growqr.io/v1/links

2. X-API-Key header:

curl -H "X-API-Key: growqr_live_abc123..." \
  https://api.growqr.io/v1/links

3. Query parameter (least secure — use only for testing):

curl "https://api.growqr.io/v1/links?api_key=growqr_live_abc123..."

The Authorization: Bearer method is recommended because most HTTP libraries, API gateways, and infrastructure tools handle Bearer tokens natively with built-in redaction in logs.

Step-by-Step Usage

Creating an API Key

1. Navigate to Dashboard → Settings → API Keys.
2. Click Create API Key.
3. Enter a descriptive name (e.g., "CI/CD Pipeline", "Zapier Integration", "Mobile App").
4. Select the permission scope: Read or Read + Write.
5. Optionally set an expiration date. Keys without an expiration remain valid until manually revoked.
6. Click Generate Key.

The key is displayed once. Copy it immediately and store it in a secrets manager, environment variable, or vault. You cannot retrieve the full key after closing the dialog.

API Key Created
──────────────────────────────────────────
Name:       CI/CD Pipeline
Key:        growqr_live_7f3a9b2c...d4e1  (shown once)
Scope:      Read + Write
Expires:    Never
Created:    2026-03-05

Testing Your API Key

Verify the key works with a simple API call:

curl -s -H "Authorization: Bearer growqr_live_7f3a9b2c...d4e1" \
  https://api.growqr.io/v1/links?limit=1 | jq .

Expected response:

{
  "data": [
    {
      "id": "link_abc123",
      "short_url": "https://go.yourcompany.com/demo",
      "destination_url": "https://yourcompany.com/product/demo",
      "clicks": 1423,
      "created_at": "2026-02-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 247,
    "page": 1,
    "limit": 1
  }
}

Creating a Link via API

curl -X POST https://api.growqr.io/v1/links \
  -H "Authorization: Bearer growqr_live_7f3a9b2c...d4e1" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_url": "https://yourcompany.com/blog/new-feature",
    "alias": "new-feature",
    "domain": "go.yourcompany.com",
    "tags": ["blog", "product-update"],
    "utm_source": "twitter",
    "utm_medium": "social",
    "utm_campaign": "feature-launch"
  }'

Rotating an API Key

Key rotation replaces an existing key with a new one while keeping the same name and permissions. This is critical if a key is compromised or as part of a regular security hygiene schedule.

1. Navigate to Dashboard → Settings → API Keys.
2. Find the key you want to rotate.
3. Click the three-dot menu (⋯) and select Rotate Key.
4. A new key is generated. The old key remains valid for a grace period of 24 hours to give you time to update integrations.
5. Copy the new key and update your integration. After 24 hours, the old key is automatically revoked.

Revoking an API Key

1. Navigate to Dashboard → Settings → API Keys.
2. Click the three-dot menu (⋯) next to the key.
3. Select Revoke. The key is invalidated immediately — any request using it returns 401 Unauthorized.

Best Practices

• Use separate keys for separate integrations. If your CI/CD pipeline and Zapier both need API access, create two keys. If one is compromised, you revoke only the affected key without breaking other integrations.
• Prefer Read scope when Write isn't needed. A dashboard or reporting integration that only fetches analytics should use a Read-only key. This limits blast radius if the key leaks.
• Store keys in a secrets manager, not in source code, environment files committed to version control, or shared documents. Use tools like AWS Secrets Manager, HashiCorp Vault, Doppler, or your CI platform's built-in secrets store.
• Set expiration dates for temporary integrations. If a contractor needs API access for a two-week project, create a key that expires in 14 days. No need to remember to revoke it manually.
• Rotate keys every 90 days as a security baseline. Automate rotation with the API's key management endpoints if your infrastructure supports it.
• Monitor API key usage. The API Keys dashboard shows the last-used timestamp and request count for each key. Keys that haven't been used in 30+ days should be investigated and potentially revoked.
• Never pass keys in query parameters in production. Query parameters appear in server logs, browser history, and proxy caches. Use the Authorization header or X-API-Key header instead.

Example Workflows

Automated Link Creation from a CMS

1. Your CMS publishes a new blog post.
2. A post-publish webhook fires and triggers a serverless function.
3. The function calls the GrowQR API with a Read+Write key to create a short link for the blog post.
4. The returned short URL is written back to the CMS for social sharing.
5. All links are tagged automatically with source:cms and the post's category.

Nightly Analytics Export

1. A scheduled cron job runs at midnight.
2. The script calls GET /v1/analytics/workspace?range=yesterday using a Read-only API key.
3. The JSON response is transformed into a CSV and uploaded to a shared Google Drive folder.
4. The marketing team reviews yesterday's performance each morning without logging into GrowQR.

CI/CD Link Validation

1. Your deployment pipeline includes a step that verifies all production short links still resolve correctly.
2. A script calls GET /v1/links?tags=production with a Read-only key.
3. For each link, the script performs an HTTP HEAD request against the short URL and checks for a 301 or 302 redirect.
4. If any link fails, the pipeline sends an alert to Slack and blocks the deployment.