Shorty - User Guide¶

Shorty is a self-hosted URL shortener that runs on your own custom domain. It provides a browser admin panel for managing short links and a REST API for programmatic access.

Table of Contents¶

1. Deploying Your Instance
2. Logging In
3. Creating a Short Link
4. Managing Existing Links
5. IP Whitelist
6. API Access
7. Using Shorty From CodeFetch
8. Lost API Key
9. Security
10. Quick Reference

Deploying Your Instance¶

Before you can use Shorty, you need to deploy your own instance. This is a one-time self-serve setup.

You must have an active CodeFetch account to deploy a Shorty instance, and only one Shorty instance is allowed per account email address. If you already have one, the deploy flow will tell you rather than let you create a second.

1. Go to https://codefet.ch/deploy.
2. Enter your CodeFetch account email address and click Send verification code.
3. Check your email for a 6-digit code and enter it. The code expires after 15 minutes — request a new one if it lapses.
4. Enter the domain you want to use for your shortener (e.g. links.yourcompany.com).
5. Copy your API key — you will not be able to retrieve it again.
6. Tick I have copied my API key and click Deploy.
7. Add the DNS records shown to your domain provider:
8. CNAME pointing to {your-tenant-id}.codefet.ch
9. One or two TXT records for SSL validation — if two _acme-challenge records are shown, add both; some providers issue a second one during renewal, and Shorty may show either or both depending on timing
10. One TXT record for hostname ownership
11. Wait for DNS propagation (typically 1–30 minutes). The page polls automatically and advances when your domain goes live.
12. You will receive a confirmation email and the admin panel link is shown on screen.

Your admin panel is at https://links.yourcompany.com/admin.

Keep your API key safe. It cannot be recovered. If lost, you must re-provision a new instance.

Logging In¶

Navigate to https://links.yourcompany.com/admin (replace with your domain).

Enter your API key in the password field and click Unlock. The admin panel is revealed on success. An incorrect key shows an error and the login screen remains.

The key is held in memory for your session only — it is never stored in the browser. Closing the tab or clicking Sign out in the header clears it.

Creating a Short Link¶

In the New link form at the top of the admin panel:

1. Enter the destination URL in the Long URL field.
2. Optionally enter a Short slug (e.g. deploy). Leave blank to auto-generate a 6-character slug.
3. Optionally tick Lock to IP whitelist to restrict who can follow this link (see IP Whitelist).
4. Click Create.

The new link appears in the list immediately. Click the short URL in the list to copy it to your clipboard.

Managing Existing Links¶

The link list shows all your short links with their slugs and destination URLs.

Filtering¶

Type in the Filter by prefix box to narrow the list to slugs starting with that text.

Editing a destination¶

Click the URL in any row to edit it inline. Press Enter or click away to save.

Toggling restricted status¶

Each row has a lock button (🔓 open / 🔒 locked). Click it to toggle whether the link enforces the IP whitelist without changing its destination URL.

Deleting a link¶

Click the Delete button on any row and confirm the prompt. Deletion is permanent and immediate.

Pagination¶

If you have more links than fit on one page, a Load more button appears at the bottom of the list. Links load in pages of up to 100.

IP Whitelist¶

The IP whitelist lets you restrict specific links so only approved IP addresses can follow them.

Setting up the whitelist¶

1. Scroll to the IP Whitelist card in the admin panel.
2. Enter one IPv4 address or CIDR range per line (e.g. 203.0.113.42 or 192.168.1.0/24).
3. Click Save.

An empty whitelist means no restriction — even links marked as restricted will allow all IPs.

Restricting a link¶

When creating a link, tick Lock to IP whitelist. For existing links, use the lock button (🔒) in the link list.

When someone follows a restricted link, their IP is checked against the whitelist. A non-matching IP receives a 403 Forbidden response.

IPv6 addresses are not supported. IPv6 clients will always be blocked on restricted links.

API Access¶

All admin operations are available via REST API. Include your API key as a Bearer token on every request.

Base URL: https://links.yourcompany.com

Create or update a link¶

curl -X POST https://links.yourcompany.com/admin \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"short": "deploy", "url": "https://example.com/deploy-guide"}'

To auto-generate a slug, omit short or pass "auto": true.

To mark a link as restricted, add "restricted": true.

Delete a link¶

curl -X DELETE https://links.yourcompany.com/admin \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"short": "deploy"}'

List links¶

curl -s "https://links.yourcompany.com/admin/list" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

Optional query params: prefix=<text> to filter, cursor=<value> from a previous response for pagination.

Get IP whitelist¶

curl -s https://links.yourcompany.com/admin/whitelist \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

Save IP whitelist¶

curl -X POST https://links.yourcompany.com/admin/whitelist \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whitelist": ["203.0.113.42", "192.168.1.0/24"]}'

Pass {"whitelist": []} to clear the whitelist.

Using Shorty From CodeFetch¶

Once your instance is deployed, connect it to your CodeFetch web app account and CLI so shared links get an automatic vanity URL alongside the full signed link.

From the web app: open your CodeFetch account settings and click Configure Shorty, then enter your Shorty admin URL and API key. They're encrypted client-side before being sent — CodeFetch never sees them in plaintext. After that, creating a shared link (Create Link) also registers a short URL automatically.

From the CLI: run codefetch shorty to store the same credentials locally alongside your CodeFetch config — see the CLI guide for the TUI keybindings this unlocks (Ctrl+Y to push a link, Ctrl+U to update credentials).

Either way, the redirect behaves the same: following the short URL redirects straight to the destination, subject to the IP whitelist if the link is restricted.

Lost API Key¶

There is no recovery path. The API key is stored only as a hash — it cannot be reversed.

If you lose your key, you must re-provision a new Shorty instance. This creates a new tenant with an empty link list. All previous short links stop working.

Security¶

• API key — generated in your browser during deploy and shown once. Only its SHA-256 hash is stored server-side; there is no way to recover a lost key.
• Short link destinations — every link's destination URL (and its slug) is AES-256-GCM encrypted before being written to storage.
• Short link lookups — the key used to look up a link by its slug is a SHA-256 hash of the slug, not the slug itself — so a direct read of the underlying storage reveals which slugs exist as hashes, not as readable text, while the AES-encrypted payload (the slug and destination together) is what gets decrypted and returned once the correct link is found. In short: finding a link doesn't require reading a plaintext slug from storage, and the destination is never stored unencrypted.

Quick Reference¶