MASK
← Back to Blog

Engineering

API-First Link Management: Building Integrations with MASK

Admin
apiwebhooksintegrationsdeveloperengineering

Why API-First Matters


Manually creating short links through a dashboard works fine when you are sharing a handful of URLs per week. But when your platform generates thousands of links — for user referrals, order confirmations, dynamic content, or partner campaigns — you need programmatic access. MASK's REST API was designed from day one to be the primary interface, not an afterthought bolted onto a GUI.


Every feature available in the MASK dashboard is accessible through the API. Create links, update destinations, manage domains, pull analytics, configure QR codes, and administer workspaces — all through clean, well-documented endpoints.



Authentication and Scoped API Keys


MASK uses scoped API keys for authentication. Each key is tied to a specific workspace and can be restricted to specific permission sets:



  • Read-only keys: Can fetch link data and analytics but cannot create or modify resources. Ideal for dashboards and reporting integrations.

  • Write keys: Can create and update links, QR codes, and campaigns. Used by backend services that generate links programmatically.

  • Admin keys: Full workspace access including domain management, team administration, and billing. Restrict these to infrastructure and DevOps tooling.


API keys are passed via the Authorization: Bearer <key> header. All API traffic is encrypted over HTTPS, and rate limits are applied per key to prevent abuse — 1,000 requests per minute for standard plans, with higher limits available on enterprise tiers.



Core API Patterns


Here is a quick overview of the most commonly used endpoints:



  • POST /api/v1/links — Create a new short link. Accepts destination, slug (optional), domain, expiresAt, utm parameters, and tags.

  • GET /api/v1/links/:id/stats — Retrieve click analytics for a specific link, including time series data, geographic breakdown, and device distribution.

  • PATCH /api/v1/links/:id — Update a link's destination, expiry, or metadata without changing the short URL.

  • POST /api/v1/qr-codes — Generate a QR code linked to an existing short link, with customization options for color, logo, and format.

  • GET /api/v1/campaigns/:id — Retrieve campaign details including all associated links and aggregate analytics.



Webhooks: Real-Time Event Streaming


For use cases that require real-time awareness, MASK supports 20 webhook event types. Configure an endpoint in your workspace settings, select the events you care about, and MASK will send signed HTTP POST requests to your server as events occur:



  • link.created, link.updated, link.deleted — Track link lifecycle changes.

  • analytics.spike, analytics.geo_anomaly — Be told when a link's click rate breaks out of its own baseline, or when clicks start arriving from an unexpected geography. MASK does not send a webhook per click: click records are written by a batched drain, so a per-click webhook could not be real-time and one backlog pass would reach your endpoint as a flood.

  • campaign.created, campaign.updated — Monitor campaign changes across your team.

  • domain.verified — Get notified when a custom domain crosses into a verified state.


Each webhook payload includes a signature header that you should verify to ensure the request originated from MASK. The signing secret is displayed once when you create the webhook endpoint.



Integration Ideas


Here are some popular ways teams are using the MASK API:



  • E-commerce platforms: Automatically generate branded short links for every order confirmation and shipping notification email.

  • CRM integrations: Create tracked links for sales outreach and feed click data back into your CRM for lead scoring.

  • CI/CD pipelines: Generate preview links for staging deployments and share them with QA teams via Slack or Teams.

  • Content management: When a new blog post is published, automatically create a short link and QR code for social sharing.