Authentication

Shortnd public API auth is a two-step flow:

1. Mint a long-lived API key in the dashboard (one-time per integration).
2. Exchange the key for a short-lived bearer token (every 15 minutes, programmatically).

Every other request to /api/v1/* carries the bearer token.

Mint an API key

API keys are minted from the Shortnd dashboard.

1. Sign in and open Settings → API Keys at shortnd.com/dashboard/settings/api-keys.
2. Click Create API key.
3. Give it a memorable name (e.g. Postman — local dev, prod ingestion).
4. Pick the scopes the key needs. Defaults grant the read + write scopes most integrations need; trim them down for least-privilege keys.
5. (Optional) Set an expires at date. Omit for non-expiring keys.
6. Click Create. The secret (snd_live_xxx.yyy) is shown once — copy it immediately into your secret store. Shortnd cannot recover it later; rotate the key if you lose the secret.

Available scopes

Scope	What it allows
urls:read / urls:write	List, create, update, delete short URLs (single + bulk).
qr:read / qr:write	Generate, list, update, delete QR codes; read scans.
domains:read / domains:write	List custom domains; add and verify new ones.
webhooks:read / webhooks:write	Manage webhook subscriptions and inspect deliveries.
analytics:read	Read org-wide and per-resource analytics.
usage:read	Read API operational usage and billing usage.
api_keys:read / api_keys:write	Manage other API keys (admin-only — typically dashboard-gated).

Rotate or revoke

The same dashboard page lets you rotate (mint a new secret on the same key id while invalidating the old one) and revoke (deactivate the key permanently).

API keys are tenant-scoped — every bearer token issued from a key inherits the key's organization. Cross-tenant access returns 404 / 403.

Required configuration

The public API is treated as always-on infrastructure.

• PUBLIC_API_JWT_SECRET is required
• REDIS_URL is required

If either is missing, the app should fail startup rather than serving /api/v1 with request-time auth errors.

1. Exchange the API key

Send the long-lived secret in the Authorization header:

curl -X POST https://shortnd.com/api/v1/auth/token \
  -H "Authorization: ApiKey snd_live_xxx.yyy"

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJ...",
    "tokenType": "Bearer",
    "expiresIn": 900,
    "organizationId": "org_uuid",
    "apiKeyId": "key_uuid",
    "scopes": ["urls:read", "urls:write", "domains:read"]
  }
}

2. Use the bearer token

curl https://shortnd.com/api/v1/urls \
  -H "Authorization: Bearer eyJ..."

Operational notes

Token exchange depends on both PostgreSQL and Redis.

• Redis is used for centralized rate limiting.
• PostgreSQL is used to resolve the API key record and organization linkage.

Expected failure modes:

• 503 RATE_LIMIT_BACKEND_UNAVAILABLE: Redis-backed rate limiting is genuinely unavailable.
• 500 SERVER_ERROR: operational backend issue such as PostgreSQL connection exhaustion.

The public API rate-limit layer now waits briefly for Redis readiness on cold start, so a momentary Redis connect race should not fail token exchange anymore.

Scope model

Current scopes:

• urls:read
• urls:write
• analytics:read
• domains:read
• domains:write
• webhooks:read
• webhooks:write
• usage:read
• api_keys:read
• api_keys:write

Session-managed key lifecycle

Tenant admins create, rotate, and revoke keys from a signed-in dashboard session through:

• GET /api/v1/api-keys?organizationId=...
• POST /api/v1/api-keys
• POST /api/v1/api-keys/{id}/rotate
• POST /api/v1/api-keys/{id}/revoke

Those endpoints are for dashboard UX and operational tooling. External vendors should use bearer-authenticated /api/v1 resource routes.