On This Page
Frequently Asked Questions (FAQ)
General Questions
Q: What is OpenShort.link?A: OpenShort.link is a self-hosted URL shortener and link tracking platform built for Cloudflare Workers. It allows you to create short links, track analytics, manage domains, and integrate via API.
Q: Do I need a Cloudflare account?A: Yes, OpenShort.link is designed to run on Cloudflare Workers and requires a Cloudflare account with Workers enabled.
Q: Is this free to use?A: The software is open source. However, you'll need a Cloudflare Workers plan (which has a free tier with limits) and Cloudflare D1 database (also has a free tier).
Q: Can I use my own domain?A: Yes! You can add custom domains in the Domains section. You'll need to configure the routes in your Cloudflare Workers settings.
Q: How many links can I create?A: There's no hard limit in the software itself. Limits depend on your Cloudflare plan and database storage capacity.
Account & Authentication
Q: How do I create the first user account?A: Navigate to /setup and enter your SETUP_TOKEN from environment variables. Create your username, email (optional), and password. The first user automatically gets the "owner" role.
A: Password reset is not available in the UI. Contact your administrator (Owner/Admin) to reset your password or create a new account.
Q: What is Multi-Factor Authentication (MFA)?A: MFA adds an extra layer of security. After entering your password, you'll need to enter a 6-digit code from an authenticator app (like Google Authenticator) or use a backup code.
Q: How do I enable MFA?A: Go to Settings > Security > Multi-Factor Authentication, click "Enable MFA", scan the QR code with your authenticator app, and verify with a code.
Q: What if I lose my authenticator device?A: Use one of your backup codes to log in, then you can disable MFA or set up a new authenticator. Always save backup codes in a secure location.
Q: Can I have multiple user accounts?A: Yes! Owners and Admins can create additional users through Settings > User Management. Each user can have different roles and permissions.
Links & Redirects
Q: Can I change a link's slug after creation?A: No, slugs are permanent. You'll need to create a new link with the desired slug and delete the old one if needed.
Q: Can I change a link's domain after creation?A: No, domains are permanent. Create a new link on the desired domain instead.
Q: What's the difference between 301 and 302 redirects?A:
- 301 (Permanent): Tells search engines the move is permanent. Better for SEO. Browser may cache the redirect.
- 302 (Temporary): Indicates temporary redirect. Search engines won't update their index. Browser won't cache as aggressively.
A: When enabled, users from specified countries are redirected to country-specific URLs. Users from other countries use the default URL. Based on IP geolocation.
Q: How do device-specific redirects work?A: When enabled, users are redirected based on their device type (Desktop, Mobile, Tablet). Detection is based on User-Agent header. Leave a device URL empty to use the default for that device type.
Q: Can I edit multiple links at once?A: Bulk editing is available for destination URLs. Select multiple links and use the bulk edit feature. Other fields must be edited individually.
Q: What happens when I delete a link?A: The link is permanently deleted and will no longer redirect. However, historical analytics data is preserved for reporting purposes.
Analytics
Q: How quickly does analytics data appear?A: Analytics data appears in real-time. Clicks are tracked immediately and visible in analytics within seconds.
Q: Can I export analytics data?A: Yes! Every analytics page has an "Export CSV" button that downloads all data for the current filters and date range.
Q: What data is tracked?A: The system tracks: clicks, unique visitors, geographic location, device type, operating system, browser, referrer, UTM parameters, custom URL parameters, and timestamps.
Q: How long is analytics data stored?A: This depends on your analytics aggregation settings. Detailed data can be aggregated into summaries to save storage. Check Settings > Analytics Aggregation.
Q: Can I see analytics for a specific link?A: Yes! Click the "📊 Analytics" button next to any link in the links table to view detailed analytics for that specific link.
Q: What's the difference between "Total Clicks" and "Unique Visitors"?A:
- Total Clicks: Total number of times the link was clicked (includes repeat clicks)
- Unique Visitors: Number of distinct users who clicked (each user counted once)
Domains
Q: How many domains can I add?A: There's no hard limit in the software. Limits depend on your Cloudflare plan and configuration.
Q: Do I need to configure routes in Cloudflare?A: Yes! After creating a domain, you must configure the routes in Cloudflare Workers dashboard. Routes must match what you configured in the domain settings.
Q: What happens if I deactivate a domain?A: All links on that domain will stop redirecting. New links cannot be created for that domain. You can reactivate it anytime to restore functionality.
Q: Can I use subdomains?A: Yes! You can add subdomains as separate domains (e.g., short.example.com). Each domain is managed independently.
A: When enabled, users can access the dashboard using that domain. Useful if you want to use a custom domain for the dashboard itself.
Tags & Categories
Q: What's the difference between tags and categories?A:
- Categories: One category per link. Used for broad organization (e.g., "Marketing", "Support").
- Tags: Multiple tags per link. Used for detailed labeling (e.g., "social-media", "campaign-2024", "urgent").
A: Yes! Tags created without a domain selected are global. Tags created with a domain selected are domain-specific. Both types can be used together.
Q: What happens if I delete a tag or category?A:
- Tag: Removed from all links that had it, but links remain.
- Category: Links lose their category assignment, but links remain.
A: Yes! Edit the tag and use the color picker to choose a new color. The change applies to all links using that tag.
API Integration
Q: How do I get an API key?A: Go to Integrations > API Keys, click "Create API Key", configure settings, and save the key immediately (it's only shown once).
Q: Can I use the same API key for multiple applications?A: Yes, but for security, it's recommended to create separate keys for different applications or environments.
Q: What is domain scoping?A: Domain scoping restricts an API key to only access specific domains. Useful for limiting access or creating keys for specific projects.
Q: What is IP whitelisting?A: IP whitelisting restricts API key usage to specific IP addresses. Only requests from whitelisted IPs will be accepted. Useful for server-to-server integrations.
Q: Can I test API endpoints without writing code?A: Yes! Use the API Playground in Integrations > Manual Integration. You can test any endpoint, see requests/responses, and copy cURL commands.
Q: What happens if my API key expires?A: API requests will fail with authentication errors. Create a new API key and update your applications. You can set keys to never expire.
Q: How do I revoke an API key?A: Go to Integrations > API Keys, find the key, and click "Delete" or "Revoke". The key will be immediately invalidated.
Import & Export
Q: What format should my CSV file be?A: CSV files should have columns for: slug, destination_url, title, description, redirect_code, category, tags. The delimiter can be comma, tab, semicolon, or pipe.
A: Yes! Include category (name) and tags (comma-separated names) columns. Tags and categories will be created if they don't exist.
A: After import, review the error report. Common issues: invalid URLs, duplicate slugs, or malformed data. Fix the CSV and re-import.
Q: Can I export filtered links?A: Yes! Apply your filters (search, tags, categories), then click "Export CSV". Only the filtered/visible links will be exported.
Status Monitoring
Q: How often are link statuses checked?A: This is configurable in Settings > Status Check Configuration. Default is typically every 24 hours, but you can customize the interval.
Q: What does each status code mean?A:
- 200 OK: Destination is working
- 301/302: Redirect (normal)
- 404: Page not found
- 500: Server error
- Timeout: Request took too long
- Unknown: Unable to determine status
A: Yes! Go to Link Monitor, find the link, and use the recheck feature. You can also select multiple links and recheck them all.
Q: What should I do if a link shows 404 or 500?A: Check the destination URL directly. If it's broken, edit the link to update the destination URL. If it's temporary, the status will update on the next check.
Settings & Configuration
Q: What user roles are available?A: Four roles:
- Owner: Full access, can manage users (first user only)
- Admin: Full access, can manage users
- Editor: Can create/edit links and domains, cannot manage users
- Viewer: Read-only access
A: No, only Owners/Admins can change user roles through Settings > User Management.
Q: What is analytics aggregation?A: Analytics aggregation pre-calculates analytics data to improve performance. Instead of computing analytics on-demand, data is aggregated at intervals. Configurable in Settings > Analytics Aggregation.
Q: What is the audit log?A: The audit log records all actions performed in the system: who did what, when, and what changed. Useful for tracking changes, troubleshooting, and security compliance.
Q: Can I see who made changes to my links?A: Yes! Check the Audit Log in Settings. It shows all create, update, and delete actions with user information.
Technical Questions
Q: What browsers are supported?A: Modern browsers including Chrome, Firefox, Safari, Edge. The interface is responsive and works on mobile browsers.
Q: Can I use this on mobile?A: Yes! The interface is fully responsive and optimized for mobile devices. All features are accessible on mobile.
Q: How do I enable dark mode?A: Click the theme toggle button (🌙) in the top navigation bar. Your preference is saved automatically.
Q: Can I customize the interface?A: The interface supports light/dark themes. Further customization would require modifying the source code.
Q: Is my data secure?A: Security features include:
- CSRF protection on all forms
- Input validation and sanitization
- Role-based access control
- API key authentication
- IP whitelisting options
- MFA support
- Audit logging
A: Data is stored in Cloudflare D1 (SQLite database) and Cloudflare Analytics Engine (for analytics). All data stays within your Cloudflare account.
Q: Can I backup my data?A: You can export links to CSV. For full backups, you'll need to backup your Cloudflare D1 database directly through Cloudflare's tools.
Q: What happens if Cloudflare Workers goes down?A: Links will stop redirecting until the Worker is back online. Analytics data is stored separately and won't be lost.
Troubleshooting
Q: My links aren't redirecting. What's wrong?A: Check:
- Domain status is "active"
- Routes are configured in Cloudflare Workers
- Link status in Link Monitor
- Destination URL is valid and accessible
A: Possible reasons:
- No clicks have occurred yet
- Date range doesn't include dates with clicks
- Filters are too restrictive
- Try "All Time" and remove all filters
A: Check:
- Domain format is valid
- At least one route is configured
- You have Editor/Admin/Owner role
- Domain name is unique
A: Check:
- API key is correct and not expired
- IP address is whitelisted (if IP whitelist enabled)
- Domain scope includes the domain you're accessing
- Request format is correct (Authorization header, etc.)
A: Review the error report. Common issues:
- Invalid destination URLs (must include http:// or https://)
- Duplicate slugs
- Invalid CSV format
- Missing required fields
A: Contact your administrator (Owner/Admin) to reset your password. Password reset is not available in the UI for security reasons.
Q: My sidebar disappeared. How do I get it back?A: Look for the "Show Sidebar" button on the left edge of the screen. On mobile, the sidebar may be hidden by default - use the menu button if available.
---