Overview

Custom URLs are the core primitive of Snapp.

A URL in Snapp is not just a shortcode redirect mapping. It is a structured entity with:

  • ownership
  • organizational scope
  • optional secrecy
  • lifecycle rules
  • permission-based access
  • security checks at creation and resolution time

All enforcement happens server-side.

URL model

Each shortened URL is defined by:

  • a target URL (originalUrl)
  • an optional shortcode
  • an owning user
  • an owning organization
  • optional teams
  • optional tags
  • optional expiration
  • optional secret
  • runtime state (active / disabled)
  • accumulated metrics

URLs are always scoped to an organization, derived from the active host.

Creation flow

Preconditions

To create a URL:

  • The user must be authenticated
  • The active host must be recognized
  • Organization context must be resolvable from the host
  • Rate and quota limits must allow creation

If teams are specified, the user must have create permission on at least one of them.

Limits enforcement

During creation, Snapp checks:

  • maxSnappPerUser (per host)
  • Host-level limits enablement

If limits are enabled and exceeded, creation is rejected.

URL validation

Before persisting a URL:

  1. The destination domain is extracted
  2. The domain is checked against the internal watchlist
  3. The domain is validated via VirusTotal (if configured)

A URL is rejected if:

  • The domain is blacklisted
  • VirusTotal marks it as unsafe
  • The API check fails

These checks are mandatory and cannot be bypassed client-side.

Shortcode handling

  • Shortcodes are optional
  • Empty or whitespace-only values are ignored
  • If omitted, a shortcode is generated
  • Collisions are handled at database level
  • Shortcodes are unique per organization, not globally

Expiration

URLs may define an expiration time.

  • Expiration is stored as an absolute timestamp
  • Expired URLs are automatically disabled during resolution
  • Expired URLs are never redirected

Secrets (protected URLs)

URLs can be protected by a secret.

Behavior:

  • The secret is hashed before storage
  • The original value is never persisted
  • On access, users must submit the secret
  • Failed attempts are logged
  • Successful validation results in a normal redirect

Update flow

Updating a URL enforces ownership or permission checks.

A user can update a URL if:

  • They are the owner
  • They are an admin
  • They have update permission on at least one associated team

Updateable fields include:

  • destination URL
  • expiration
  • secret
  • tags
  • teams
  • UTM parameters
  • active state

All updates run inside a transaction.

Enable / disable URLs

URLs can be toggled active or inactive.

Rules:

  • Owners can toggle their URLs
  • Admins can toggle any URL
  • Team members require update permission

Disabled URLs:

  • Are not redirected
  • Return a disabled state
  • Are logged as not found

Deletion

URLs can be deleted in bulk.

Deletion rules:

  • Admins can delete any URL
  • Owners can delete their own URLs
  • Team members must have delete permission on all associated teams

If no deletable URLs are found, the operation is aborted.

Resolution flow

When a shortcode is requested:

  1. Expired URLs are disabled
  2. The system attempts resolution in order:
    • Organization-specific match
    • Case-insensitive fallback (if enabled)
    • Global fallback (oldest match)
  3. If no match is found, the request is logged as not found

Case-insensitive fallback

If disable.lowerCaseFallback is false:

  • xYz can resolve xyz
  • Resolution is scoped to the organization
  • Exact matches always win

If disabled, only exact matches are allowed.

Secret-protected resolution

If a URL has a secret:

  • The redirect is paused
  • The user is presented with a secret form
  • The URL is redirected only after successful validation

Secrets are validated server-side using constant-time checks.

Runtime safety checks

Before redirecting:

  • Destination domain is revalidated
  • Watchlist rules are re-applied
  • VirusTotal is checked again

If a URL becomes unsafe after creation, it is blocked at resolution time.

UTM handling

URLs may define UTM parameters.

On redirect:

  • UTMs are injected into the destination URL
  • Existing query parameters are preserved
  • Order is deterministic

UTMs are also used for metrics aggregation.

Metrics and logging

Each resolution attempt is logged:

  • Successful visits
  • Invalid secrets
  • Disabled URLs
  • Not found URLs

Metrics are collected only server-side.

Guarantees

  • URL resolution is deterministic
  • Permissions are enforced server-side
  • Secrets are never stored in plain text
  • Unsafe URLs are blocked even after creation
  • Organization boundaries are never crossed

Notes

  • There is no client-side trust
  • All checks are repeatable and auditable
  • URL behavior may change at runtime if:
    • configuration changes
    • security integrations flag a domain
    • the URL expires