Authentication

Every request to the TrimLink API carries an API key. A key belongs to one account, carries a set of scopes, and works on the Pro, Growth and Teams plans. This page covers how to send a key, what each scope unlocks, and the exact errors you get when something is off.

Send your key

Put the key in the X-API-Key header. It is the header the API checks first.

curl https://trimlink.co/api/v1/stats/my-link \
  -H "X-API-Key: tk_live_your_api_key"

The API also accepts Authorization: Bearer, as long as the token starts with tk_. When a request carries both headers, X-API-Key wins. A Bearer token without the tk_ prefix is not read as a key at all, so that request fails with 401 Authentication required.

curl -X POST https://trimlink.co/api/v1/shorten \
  -H "Authorization: Bearer tk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"destinationUrl": "https://example.com/spring-sale"}'

Once a key header is present, the request is checked against that key only. It never falls back to a logged-in browser session, so a bad key fails loudly instead of quietly borrowing someone's login.

Create and manage keys

Create keys in Dashboard, Settings, API. Give each key a name and tick its scopes. A key needs at least one scope.

A key acts in its owner's personal workspace. Links it creates land there, and it reads only links that live there. Team workspace links are managed in the dashboard.

The full key is shown once, right after you create it. TrimLink stores only a SHA-256 hash of the key, so nobody can show it to you again, support included. If you lose a key, revoke it and create a new one.

The key list shows each key's name, its prefix with the rest masked, its scopes, when it was created and when it was last used. Last used updates whenever the key is sent with a request, which makes it easy to spot keys nothing calls anymore. Keys created in the dashboard have no expiry date. They work until you revoke them, and a revoked key is refused on the very next request.

Key format

  • tk_live_ followed by 64 hex characters (32 random bytes). This is the key the dashboard creates.
  • tk_test_ is a second prefix the key check accepts. It is only a label. There is no separate sandbox: a test-prefixed key reads and writes the same live data and counts against the same daily limit.

Any other prefix is rejected before the database is touched, with 401 Invalid API key.

Scopes

Pick only what the integration needs. A script that creates links needs links:write and nothing else. A reporting job needs analytics:read and links:read.

ScopeWhat it allows
links:readRead link data and analytics
links:writeCreate, update, and delete links
analytics:readRead analytics data
domains:readRead custom domains
domains:writeManage custom domains
tags:readRead tags and the tags on links
tags:writeCreate, rename, and delete tags, and tag links
utm:readRead UTM templates and apply them to URLs
utm:writeCreate, update, and delete UTM templates
webhooks:writeCreate and delete webhook subscriptions

Which endpoint needs which scope

EndpointScope
POST /api/v1/shortenlinks:write
POST /api/v1/links, PATCH or DELETE /api/v1/links/:idlinks:write
POST /api/v1/links/import, PATCH /api/v1/links/:id/movelinks:write
GET /api/v1/stats/:codeanalytics:read and links:read
GET /api/v1/links/:id/qrlinks:read
POST or PATCH /api/v1/links/:id/qrlinks:write
GET /api/v1/folderslinks:read
POST /api/v1/folders, PATCH or DELETE /api/v1/folders/:idlinks:write
GET /api/v1/domains and /api/v1/domains/:id/statusdomains:read
POST /api/v1/domains, DELETE /api/v1/domains/:iddomains:write
Zapier subscribe, unsubscribe and auth testwebhooks:write

The stats endpoint asks for both read scopes because its response includes the destination URL and link details, not only click counts. A key made for reporting cannot read destination URLs unless it also holds links:read.

Plans, daily limits and key counts

The API starts on Pro. Each account gets a daily request budget, shared by all of its keys and counted over a rolling 24 hours, not a calendar day.

PlanAPI requestsActive keys
Free and StarterNo API access0
Pro1,000 a day1
Growth10,000 a day5
TeamsUnlimitedUnlimited

Compare plans on the pricing page.

What every request checks

  1. The key exists, is not revoked, and has not expired.
  2. The key holds every scope the endpoint needs.
  3. The account's current plan still includes the API. Moving below Pro switches every key off at once, without anyone revoking them, and moving back turns them on.
  4. The account is still under its daily request limit.

Authentication errors

These errors come back as JSON with one error string, for example {"error":"Invalid API key"}. Errors from inside an endpoint use the standard error format.

StatuserrorCause
401Invalid API keyThe key is unknown, mistyped, or does not start with tk_live_ or tk_test_.
401API key has expiredThe key passed its expiry date.
401API key has been revokedSomeone revoked the key.
401Authentication requiredNo key reached the server. A Bearer token that does not start with tk_ is ignored, so this is also what a malformed Authorization header returns.
403Missing required scope(s): …The key lacks a scope the endpoint needs. The message names each missing scope.
403API access is not available on your current plan. Upgrade to Pro or higher.The account moved below Pro. Its keys stop working until the plan is Pro again.
429Daily API rate limit reached (N requests). Resets in 24h.The account used its daily budget. The body also carries a remaining field. There are no rate limit headers.

Keep keys safe

  • Use keys from server code only. Never ship one in a browser bundle or a mobile app, where anyone can read it.
  • Keep keys in environment variables, never in the repository.
# .env.local
TRIMLINK_API_KEY=tk_live_your_api_key
  • On plans with more than one key, give each integration its own key with the fewest scopes. You can then revoke one without breaking the others.
  • To rotate, create the new key, deploy it, then revoke the old one. Its last used date tells you when traffic has moved over.

Next steps