LinkTrace docs

Authenticate once, scope tightly, track on the server

LinkTrace public API access is designed around secret Bearer keys, machine users, and route scopes. Use session auth for dashboard actions and secret keys for your own backend.

Authentication model

Do not mix dashboard session behavior with external integrations.

Session cookies

Use session auth for the LinkTrace dashboard. This is not the right auth model for your own backend integrations.

Secret Bearer keys

Use secret keys from your backend or CI. Scope them to the smallest route group that still lets the job complete.

Publishable keys

Publishable keys are only for conversion write flows. They are not a general public API credential.

Minimal authenticated request

Every external server-side request should send a secret Bearer key.

bash

curl 'https://api.linktrace.cc/api/v1/links' \
  -H 'Authorization: Bearer lt_your_secret_key' \
  -H 'Accept: application/json'

Public integration endpoint table

This table is the current public integration surface. It excludes dashboard-only management routes.

Public LinkTrace API endpoint groups with authentication model, scope, and plan gate details.
Group	Endpoints	Auth	Scope	Plan gate
Links	`GET /api/v1/linksPOST /api/v1/linksGET /api/v1/links/:idPATCH /api/v1/links/:idDELETE /api/v1/links/:idGET /api/v1/links/:id/detailGET /api/v1/links/:id/events/export`	Session, secret Bearer	`links`	Advanced detail is paid. Export is paid. Some link controls are separately gated by plan.
Analytics	`GET /api/v1/analytics/overviewGET /api/v1/analytics/reportGET /api/v1/analytics/chartGET /api/v1/analytics/traffic_panelGET /api/v1/analytics/acquisition_panelGET /api/v1/analytics/geo_panelGET /api/v1/analytics/technology_panel`	Session, secret Bearer	`analytics`	Advanced analytics is currently starter and above.
Conversions	`GET /api/v1/conversions/summaryGET /api/v1/conversions/eventsGET /api/v1/conversions/events/exportPOST /api/v1/track/leadsPOST /api/v1/track/salesGET /api/v1/track/client.js`	Session, secret Bearer, publishable on writes	`conversions`	Conversion tracking currently requires creator or agency.
Domains	`GET /api/v1/domainsGET /api/v1/domains/checkPOST /api/v1/domainsPATCH /api/v1/domains/:idPOST /api/v1/domains/:id/verifyDELETE /api/v1/domains/:id`	Session, secret Bearer	`domains`	Domain count is plan-limited. Metadata control is a separate plan gate.
Folders / Tags / UTM templates	`GET\|POST\|PATCH\|DELETE /api/v1/link_foldersGET\|POST\|PATCH\|DELETE /api/v1/link_tagsGET\|POST\|PATCH\|DELETE /api/v1/utm_templates`	Session, secret Bearer	`folders, tags, utm_templates`	Workspace quotas and plan limits still apply after auth succeeds.

Not part of the public integration API

A secret Bearer key should not be able to operate internal dashboard management surfaces.

Workspace settings

Memberships

Billing mutations

API keys

Machine users

Metadata cards

QR management

Conversion provider connections

Scope strategy

Use the smallest scope set that matches the integration surface.

links for short-link CRUD and link detail reads.
analytics for report and export reads.
domains, folders, tags, and utm_templates for their respective workspace surfaces.
conversions for server-side lead and sale tracking plus conversion summary and events reads.

Retries and idempotency

Treat conversion delivery as an at-least-once integration. Your side should retry safely.

Generate stable event ids for your own lead and sale events when you can.
Retry on network failures, timeouts, and 5xx responses from LinkTrace.
Do not retry blindly on 4xx responses without fixing the payload or credentials first.
For provider webhooks, preserve upstream provider event ids and signatures instead of inventing a second event source.

Related guides

Docs home

Start with the product model, installation path, and implementation order.

Conversion tracking

Install the tracking script once, then send lead and sale events from your backend.

Auth events

Track signup and login events from Supabase, Clerk, NextAuth, or your own backend.