Skip to content
Authentication

Authentication

Availability: API keys are available on every plan, including Free. Rate limits depend on your plan.

The Shortn API uses API keys with scopes. Create and manage keys from Profile → API keys.

Base URL and headers

Every endpoint lives under:

https://app.shortn.link/api/v1

Send your key in the Authorization header:

curl https://app.shortn.link/api/v1/links \
  -H "Authorization: Bearer $SHORTN_API_KEY"

X-API-Key: <key> works too; if you send both, X-API-Key is used. Keys begin with sk_live_. Keep them on your server — don’t embed them in frontend code.

Data access

A key is either account-wide or limited to one workspace, chosen when you create it:

  • An account-wide key works in every workspace you belong to.
  • A workspace key works only in its workspace. Asking for a link, tag, team or other resource in another workspace returns 403 api_key_workspace_mismatch. Adding, verifying and removing custom domains needs an account-wide key (403 account_scoped_api_key_required).

A key also sees only what you can see: links limited to teams you aren’t in stay hidden, unless you’re a workspace owner or administrator.

Scopes

Each key is scoped to limit what it can do. The scopes and the endpoints they unlock:

ScopeEndpoints
links:readList links (GET /links), get a link (GET /links/{public_id}). See links.
links:writeCreate (POST /links), update (PATCH), suspend (DELETE) and re-enable (POST .../enable) a link, end an A/B test with a winner (POST .../ab/winner).
analytics:readA link’s click totals (GET /analytics/links/{public_id}). See analytics.
workspaces:readList and get workspaces (/workspaces). See workspaces.
reports:read, reports:writeReport and alert rules (/reports/rules). See reports and alerts.
tags:read, tags:writeA workspace’s tags (/workspaces/{public_id}/tags, /tags/{id}). See tags.
utm-templates:read, utm-templates:writeA workspace’s UTM templates (/workspaces/{public_id}/utm-templates, /utm-templates/{id}). See UTM templates.
destinations:read, destinations:writeA workspace’s report destinations (/workspaces/{public_id}/destinations). See destinations.
teams:read, teams:writeA workspace’s teams (/workspaces/{public_id}/teams, /teams/{slug}). See teams.
domains:read, domains:writeCustom domains: list, add, verify, remove (/domains). domains:write needs an account-wide key. See domains.
conversions:readConversion summaries, events, timeline and attribution (/conversions/...). See conversions.
conversions:writeSend leads, sales and refunds, and validate them (POST /conversions/leads, .../sales, .../refunds, and their /validations).

read scopes cover the GET endpoints, write scopes the ones that change data. A write scope doesn’t include its read scope: a key that creates links and lists them needs both links:write and links:read. Give each key the narrowest scopes it needs.

A few endpoints need no key at all; see public endpoints.

Authentication errors

StatusCodeMeaning
401api_key_requiredNo key was sent.
401invalid_api_keyThe key is wrong, revoked or expired, or you’re no longer an active member of its workspace.
403api_key_scope_not_allowedThe key lacks a scope; details.required_scope names it.
403api_key_workspace_mismatchA workspace key asked for something in another workspace.
403account_scoped_api_key_requiredThe endpoint needs an account-wide key.
403api_access_unavailableThe plan has no API access.

Rate limits

Each key has two per-minute limits, set by the plan of the account the key belongs to (for a workspace key, the workspace owner’s plan):

PlanGeneral endpointsAnalytics endpoints
Free105
Starter600120
Professional600120
Agency1,200240

Analytics endpoints are the ones that need analytics:read or conversions:read; every other endpoint counts toward the general limit. Responses show the limit they count toward:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
X-RateLimit-Window: 60
X-RateLimit-Policy: default

X-RateLimit-Policy is default or analytics. Over the limit, you get 429:

{
  "code": "api_rate_limit_exceeded",
  "error": "API rate limit exceeded for the current plan.",
  "hint": "Retry after the current rate-limit window or upgrade the workspace plan.",
  "details": {
    "limit": 10,
    "window": "1 minute",
    "api_tier": "basic",
    "upgrade_url": "/profile/billing",
    "rate_bucket": "default",
    "remaining": 0,
    "reset_after_sec": 60
  }
}

Wait for the window to pass before retrying.

Errors

Errors use a consistent shape:

{
  "code": "conversion_identity_required",
  "error": "idempotency_key is required",
  "hint": "Send a stable key for this lead, such as your signup or form submission ID, so a retry is recorded once.",
  "details": {
    "field": "idempotency_key"
  }
}

code is stable and safe to branch on; error is a readable message. hint and details are present when the endpoint can add useful context, and details.field names the request field at fault. Errors from the endpoints that send leads, sales and refunds also carry a request_id, the same value as their Shortn-Request-Id response header, so you can find the call in the event log. A few older endpoints return only error.

Plan limits

When a request needs a feature your plan doesn’t include, or would go past a plan limit, you get 403, with the details at the top level:

{
  "code": "plan_limit_exceeded",
  "error": "Active links limit reached for this workspace owner's current plan.",
  "hint": "Upgrade to a plan that includes this feature or raises this limit.",
  "feature": "active_links",
  "limit": 25,
  "current": 25,
  "required_plan": null,
  "upgrade_url": "/profile/billing"
}
  • feature names what was refused. Limits: active_links, custom_domains, destination_edits, partners, report_alert_rules, team_members, utm_templates, workspaces. Features: ab_testing, conversion_tracking, custom_share_preview, custom_short_codes, device_targeting, geo_targeting, language_targeting, link_expiration, password_protected_links, public_dashboard_sharing, qr_customization, webhooks_integrations.
  • limit and current are the limit and your usage; both are 0 for a feature.
  • required_plan is the lowest plan that allows it (starter, professional or agency), or null when any higher plan raises the limit.
  • upgrade_url is the billing page in the app.

Limits follow the plan of the workspace’s owner, not of the person calling.

Status codes

StatusMeaning
200, 201Success. Creating a link returns 201.
400The request is invalid; see code and details.
401Missing or invalid API key.
403Missing scope, wrong workspace, or a plan limit.
404Not found, or not visible to this key.
409Conflict, such as a short code that’s taken.
429Rate limit.
503Analytics are temporarily unavailable; retry shortly.
Last updated on