Concepts

Authentication & Access

Linkshot uses a domain-based access model — no API key headers, no tokens. Authorization is embedded in the request URL itself.

Overview#

Unlike most APIs, Linkshot does not use an Authorization header. The two endpoints use different approaches:

Endpoint	Auth method	Suitable for
`/api/og/v1/:templateId`	Template ID in URL path	HTML meta tags, server-side rendering, static sites
`/api/preview/:clientKey`	Client key in URL + Origin header	Browser JavaScript, dynamic previews

OG API Auth Flow#

When you call GET /api/og/v1/:templateId?url=..., Linkshot performs these checks in order:

Validate the url parameter — must be present and a valid URL.
Look up the template by the templateId in the path — must exist.
Check the template owner's subscription — must be active or trialing.
Check the target domain — the hostname of the url parameter must be in the owner's registered domain list. Subdomains are allowed automatically.

Template IDs are the credential

The template ID functions like an API key for this endpoint. Anyone who knows it and a registered domain can trigger screenshot generation. Avoid exposing template IDs in public source code.

Preview API Auth Flow#

When you call GET /api/preview/:clientKey?url=... from the browser, Linkshot performs these checks:

Extract the Origin header — the browser sends this automatically. Requests from localhost or 127.0.0.1 skip all subsequent checks.
Validate the client key — look up clientKey in the database.
Validate the Origin — the origin's hostname must match a domain registered by the client key's owner. Subdomain matching applies.
Check the subscription — the key owner must have an active subscription.

Client Keys#

Every Linkshot account has exactly one client key. It is auto-generated when you first visit the Previews page and stays the same unless you regenerate it.

Key format

cl_a1b2c3d4e5f6a1b2c3d4e5f6

cl_ prefix + 24 lowercase hexadecimal characters

Find your key in Dashboard → Previews. If you regenerate it, any existing URLs using the old key will stop working immediately.

Domain Registration#

Both APIs only generate screenshots for domains you have explicitly registered. This prevents your account from being used to screenshot arbitrary websites.

Subdomain matching#

Registering a root domain automatically allows all subdomains. For example, if you register example.com, the following URLs are all allowed:

https://example.com/blog/post-1       ✓ allowed
https://www.example.com/about         ✓ allowed (www subdomain)
https://docs.example.com/api          ✓ allowed (any subdomain)
https://otherdomain.com/page          ✗ not allowed

Adding a domain

Go to Dashboard → Domains → Add domain and enter the bare hostname (e.g., example.com), without the https:// prefix.

Plans & Limits#

Your plan determines how many domains and templates you can create. All plans include a 7-day free trial — no credit card required.

Plan	Domains	Templates
Basic	1	1
Pro	3	3
Max	6	6

Attempting to create more domains or templates than your plan allows returns a 403 Forbidden error in the dashboard.