Authentication

All v1 API requests require a valid API key sent as a Bearer token.

API Key Format

Keys follow the format:

xqr_pk_{prefix}.{secret}

• Prefix (8 hex characters): Used for key lookup — safe to log
• Secret (64 URL-safe characters): The actual credential — never log this
• The full key is SHA-256 hashed server-side; we never store the plaintext

Sending the Key

Include the key in the Authorization header:

Authorization: Bearer xqr_pk_a1b2c3d4.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Scopes

Each API key is granted a set of scopes that control what it can access. Assign the minimum scopes needed for your use case.

Scope	Description
*	Full access (all scopes)
links:read	List and view short links
links:write	Create, update, and delete short links
qr:read	List and view QR templates
qr:write	Create, update, and delete QR templates
qr:render	Generate QR code images
analytics:read	Query analytics data
assets:read	List and view assets
assets:write	Upload, publish, and delete assets
bio:read	List and view Link-in-Bio pages
bio:write	Create, update, publish, and delete bio pages
reports:read	View reports
reports:write	Create and manage reports
workspace:read	View workspace info, usage, and members
webhooks:read	List and view webhook endpoints
webhooks:write	Create, update, and delete webhooks

Scope Matching

• Exact match: links:read grants read access to links
• Wildcard: * grants all scopes
• Requesting an endpoint without the required scope returns 403 Forbidden

Key Rotation

Rotate keys without downtime:

1. Go to Developers → API Keys in your dashboard
2. Click Rotate on the key you want to replace
3. The old key is revoked and a new key is created with the same name and scopes
4. Update your application with the new key

Tip

Keys can have an optional expiration date. Set expires_in_days when creating a key for automatic expiry.

Plan Requirements

API access requires a Pro plan or higher. The Free plan does not allow API key creation.

Plan	API Keys	Monthly API Calls
Free	0	0
Pro	2	1,000
Business	10	25,000
Enterprise	Unlimited	100,000

Error Responses

Status	Meaning
401 Unauthorized	Missing, invalid, revoked, or expired API key
403 Forbidden	Valid key but insufficient scopes or plan feature not available