Authentication

The AutoRanq API uses Bearer tokens. Every request includes one in the Authorization header — no OAuth handshake, no session cookies, no custom auth flow.

Authorization: Bearer ar_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Key formats

There are two key prefixes:

Prefix	Use case	Billing
ar_live_	Production traffic	Counted against your plan
ar_test_	Local development, CI, integration tests	Free, no billing

Both prefixes accept the exact same endpoints — test keys aren’t gated to a sandbox. They create real database records that are flagged as test-mode and don’t count toward your plan limits.

Caution

Test-mode resources are still real records in your account. Use them for development and tear them down with DELETE calls when done.

Creating a key

Two ways:

From the dashboard (recommended for humans)

app.autoranq.ai → Settings → API → Create API key. The full key value is shown once on creation — copy it immediately.

Via the API itself

Useful when bootstrapping a CI account or provisioning keys for end-users in your own app:

curl

curl -X POST https://api.autoranq.ai/api/public/v1/api-keys \
  -H "Authorization: Bearer $AUTORANQ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI deploy key",
    "scopes": ["read", "write"]
  }'

JavaScript

const response = await fetch(
  'https://api.autoranq.ai/api/public/v1/api-keys',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.AUTORANQ_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'CI deploy key',
      scopes: ['read', 'write'],
    }),
  }
);
const { data } = await response.json();
// data.key is shown only here — store it safely
console.log('Created key:', data.key);

Python

import os, requests

response = requests.post(
    "https://api.autoranq.ai/api/public/v1/api-keys",
    headers={
        "Authorization": f"Bearer {os.environ['AUTORANQ_KEY']}",
        "Content-Type": "application/json",
    },
    json={"name": "CI deploy key", "scopes": ["read", "write"]},
)
data = response.json()["data"]
# data["key"] is shown only here — store it safely
print("Created key:", data["key"])

The full key is in data.key. It is not retrievable later — only the first 12 characters (the “prefix”) are stored after that. If you lose it, regenerate via POST /api-keys/:id/regenerate.

Scopes

Two scopes exist:

Scope	Allows
read	GET requests on all resources
write	POST, PATCH, DELETE on all resources, plus everything read allows

You can request either or both at creation. Most integrations want read,write. Reserve read-only keys for analytics tools, dashboards, or other read-only consumers.

Note

Scopes are stored as a comma-separated string ("read,write") in the API. The list form in your POST body is for convenience — both work.

Rate limits

The default rate limit is 1000 requests per hour, enforced as a sliding window in Redis. The limit is per-key, not per-account, so independent integrations don’t compete for budget.

When you exceed the limit, requests return:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": "TOO_MANY_REQUESTS",
  "message": "Rate limit exceeded. Try again in N seconds."
}

You can request a higher limit per key by updating it:

curl -X PATCH https://api.autoranq.ai/api/public/v1/api-keys/<id> \
  -H "Authorization: Bearer $AUTORANQ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rate_limit": 5000}'

If your use case needs more than that, contact us — bulk generators and resellers get a different default.

Error responses

All authentication failures use HTTP status codes — no custom error scheme:

Status	Meaning	Common cause
401 Unauthorized	Missing, malformed, revoked, or expired key	Bearer header missing; key starts with wrong prefix; key revoked in dashboard
403 Forbidden	Key is valid but lacks required scope	Calling POST /articles with a read-only key
429 Too Many Requests	Rate limit exceeded	Burst above 1000/hour

A typical 401 body:

{
  "error": "UNAUTHORIZED",
  "message": "Missing Authorization header"
}

Rotating a compromised key

If a key leaks (e.g. accidentally committed to a public repo), rotate it immediately:

1. Generate a new key value (same ID, new secret):

   curl -X POST https://api.autoranq.ai/api/public/v1/api-keys/<id>/regenerate \
     -H "Authorization: Bearer $AUTORANQ_KEY"

   The response includes a fresh data.key value. Save it.

2. Update your application to use the new key value. Deploy.

3. Wait for traffic to drain — confirm no requests still come in with the old value (check last_used_at field).

4. Confirm rotation took effect — the old value stops working the moment regenerate succeeds (no grace period). If something is still using the old value, it’s currently broken.

If you can’t deploy a fix quickly, revoke the key entirely instead — that immediately rejects all requests:

curl -X DELETE https://api.autoranq.ai/api/public/v1/api-keys/<id> \
  -H "Authorization: Bearer $AUTORANQ_KEY"

Revoked keys are soft-deleted; you’ll still see them in the dashboard’s audit history but they can never be re-activated.

Best practices

Use env vars, never hardcode

process.env.AUTORANQ_KEY in code, .env files in .gitignore, 1Password/Vault for secrets in production.

One key per integration

CI/CD, your CMS plugin, internal dashboards — each gets a distinct key so you can revoke individually.

Use test keys in CI

Prefix ar_test_ keys cost nothing and let you run your test suite against the real API.

Audit `last_used_at`

Periodically review unused keys via GET /api-keys — anything not used in 90 days is a candidate for revocation.

Next steps

• Webhooks — stop polling, get notified when generations finish
• Quickstart — the 5-minute walkthrough if you skipped it