Auth API (cross-origin clients)
Every linked host (my.href.nz, href.nz, meinlink.at, clicked.at, href.yt, ternis.link, dash.ternis.link, … — all hosts in config/domains.php) exposes a small, CORS-protected auth API. It exists for one reason: a web app on another origin cannot read your session cookie.
If you build a companion site, a browser extension, or an embed that should act on behalf of the signed-in user, you cannot simply call the REST API — the browser will not attach the dashboard session cookie to a cross-origin request, and the REST API authenticates with bearer tokens anyway.
This API closes that gap in two steps:
GET /auth/api/session— ask whether the visitor is signed in, and who they are.POST /auth/api/token— exchange that session for a short-lived bearer token you can use against the regular REST API.
Both endpoints are served on every linked host. A login on ternis.link is handed to the other hosts through /auth/sso/start → /auth/sso/issue → /auth/sso/consume (one-time, host-bound token), so each host has its own session; signing out anywhere signs out everywhere. my.ternis.link 301-redirects to my.href.nz.
CORS: the allowlist is the gate
Cross-origin access is off by default. The operator has to list the origins that may call the API:
CORS_ALLOWED_ORIGINS="https://app.example.com,https://companion.test"
Everything else is rejected:
- A browser request from an origin that is not on the list gets HTTP 403 — the request never reaches the handler.
- The CORS headers (
Access-Control-Allow-Origin,Access-Control-Allow-Credentials: true) are only emitted for allowlisted origins, so a non-browser client cannot read the responses either. - Credentials are allowed, so the list must never contain
*. Browsers reject a wildcard with credentials anyway, and it would hand your session to every site on the internet.
The endpoints are exempt from CSRF validation, because a cross-origin client cannot produce a CSRF token. The origin allowlist takes that role: it is enforced server-side, not just in the browser.
Step 1 — ask who the visitor is
curl https://my.ternis.link/auth/api/session \
-H "Origin: https://app.example.com" \
-H "Cookie: $SESSION_COOKIE"
{
"authenticated": true,
"host": "my.ternis.link",
"user": {
"id": "01K8Z…",
"name": "Alex Example",
"email": "alex@example.com",
"plan": "free"
}
}
A visitor who is not signed in is a normal answer, not an error:
{ "authenticated": false, "host": "my.ternis.link", "user": null }
The response is always HTTP 200.
In the browser, send the session cookie with credentials: 'include':
const res = await fetch('https://my.ternis.link/auth/api/session', {
credentials: 'include',
headers: { Accept: 'application/json' },
});
const { authenticated, user } = await res.json();
Step 2 — exchange the session for a token
curl -X POST https://my.ternis.link/auth/api/token \
-H "Origin: https://app.example.com" \
-H "Cookie: $SESSION_COOKIE" \
-H "Content-Type: application/json"
{
"token": "ts_…",
"token_type": "Bearer",
"expires_at": "2026-10-21T12:15:00+00:00",
"expires_in": 900,
"host": "my.ternis.link",
"user": { "id": "01K8Z…", "name": "Alex Example", "email": "alex@example.com", "plan": "free" }
}
- The raw token is returned once and never stored — only its SHA-256 digest is, exactly like an API key.
- Without a session the endpoint answers HTTP 401.
ttlmay be sent in the body to ask for a different lifetime. It is clamped to 60 … 3600 seconds; the default is 900 (15 minutes).- Minting a token is recorded in the activity feed.
Step 3 — use the token
Session tokens are accepted as bearer tokens by the whole REST API, exactly like an API key:
curl https://links.t-api.de/v1/links \
-H "Authorization: Bearer ts_…"
The difference to an API key: a session token is short-lived, revocable and minted on demand — it is meant for a browser session, not for a server-to-server integration. Use a regular API key for that; see Accounts & API keys.
Revoking
curl -X DELETE https://my.ternis.link/auth/api/token \
-H "Origin: https://app.example.com" \
-H "Authorization: Bearer ts_…"
Answers HTTP 204. The token stops working immediately; subsequent API calls with it return HTTP 401.
Notes
- Both hosts (
my.ternis.link,my.href.nz) serve the same app and the same session. Thehostfield tells you which one answered. - Tokens expire on their own; there is no refresh token. Mint a new one when needed.
- The endpoints are rate limited (30 requests per minute per IP).
- Tokens are bound to the account that was signed in. They act with exactly that account's permissions and quota.