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.
| Scope | What it allows |
|---|---|
links:read | Read link data and analytics |
links:write | Create, update, and delete links |
analytics:read | Read analytics data |
domains:read | Read custom domains |
domains:write | Manage custom domains |
tags:read | Read tags and the tags on links |
tags:write | Create, rename, and delete tags, and tag links |
utm:read | Read UTM templates and apply them to URLs |
utm:write | Create, update, and delete UTM templates |
webhooks:write | Create and delete webhook subscriptions |
Which endpoint needs which scope
| Endpoint | Scope |
|---|---|
| POST /api/v1/shorten | links:write |
| POST /api/v1/links, PATCH or DELETE /api/v1/links/:id | links:write |
| POST /api/v1/links/import, PATCH /api/v1/links/:id/move | links:write |
| GET /api/v1/stats/:code | analytics:read and links:read |
| GET /api/v1/links/:id/qr | links:read |
| POST or PATCH /api/v1/links/:id/qr | links:write |
| GET /api/v1/folders | links:read |
| POST /api/v1/folders, PATCH or DELETE /api/v1/folders/:id | links:write |
| GET /api/v1/domains and /api/v1/domains/:id/status | domains:read |
| POST /api/v1/domains, DELETE /api/v1/domains/:id | domains:write |
| Zapier subscribe, unsubscribe and auth test | webhooks: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.
| Plan | API requests | Active keys |
|---|---|---|
| Free and Starter | No API access | 0 |
| Pro | 1,000 a day | 1 |
| Growth | 10,000 a day | 5 |
| Teams | Unlimited | Unlimited |
Compare plans on the pricing page.
What every request checks
- The key exists, is not revoked, and has not expired.
- The key holds every scope the endpoint needs.
- 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.
- 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.
| Status | error | Cause |
|---|---|---|
| 401 | Invalid API key | The key is unknown, mistyped, or does not start with tk_live_ or tk_test_. |
| 401 | API key has expired | The key passed its expiry date. |
| 401 | API key has been revoked | Someone revoked the key. |
| 401 | Authentication required | No 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. |
| 403 | Missing required scope(s): … | The key lacks a scope the endpoint needs. The message names each missing scope. |
| 403 | API 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. |
| 429 | Daily 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
- Create and update links
- Read a link's click report
- Receive webhooks (Growth and Teams)