New in the Lnki API: access tokens, QR codes and bulk imports

The API changed today in one way that needs action from existing integrations and in several ways that do not. The change that needs action: an API key is no longer accepted on data endpoints. Everything else is an addition. The API is part of the Business plan.

Access tokens replace the raw key

Until now an integration sent its API key with every request. From today the key is sent to one endpoint only, POST /api/v1/oauth/token, which exchanges it for two tokens:

• An access token, starting with lnki_at_, that lasts one hour. Send it as a bearer token with every request.
• A refresh token, starting with lnki_rt_, that lasts 30 days and works once. Post it to the same endpoint with grant_type set to refresh_token to get a new pair without sending the key again.

curl -X POST https://lnki.io/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "api_key",
    "api_key": "YOUR_API_KEY"
  }'

The response includes expires_in, which is 3600 seconds, and expires_at, so you can refresh a little early instead of waiting for a 401. When you refresh, save both new tokens: the access token and refresh token you used before stop working as soon as the new pair is issued.

What to change in an existing integration

A request that still sends a lnki_live_ key to a data endpoint is answered with 401 and the code api_key_not_allowed. To move over:

1. Keep the key where it is, in your secret manager or an environment variable. It is now used only to get tokens.
2. Exchange it for a token pair and store both tokens.
3. Send the access token in the Authorization: Bearer header of every request.
4. When a request answers 401 with the code token_expired, or shortly before expires_at, refresh and store the new pair.

POST /api/v1/oauth/revoke ends a token pair early, for example when you shut a server down. Revoking or regenerating the key on the API Keys page ends every token made from it.

QR codes

/api/v1/qr_codes creates, lists, reads, updates and deletes QR codes. Make one for a link you already have by sending link_id, or send destination_url and the link is created in the same call. A design object sets the pattern, the eye and corner styles, colours, margin, error correction, logo and label. A design value outside what an option accepts is rejected with a 422 that names each bad field.

A single code's response includes its drawing in an svg field, and GET /api/v1/qr_codes/{id}/image returns the same SVG on its own. A link has at most one QR code, so creating a code for a link that already has one updates it. Deleting a code leaves its link in place, so a code that was already printed keeps working.

Bulk imports

POST /api/v1/imports creates up to 500 links in one request. Each row needs a destination_url and can carry a slug, title, folder and tags. The request returns when every row has been processed, with the links that were made and a summary.

Rows with an invalid URL, a repeated destination or a back-half that is already taken are skipped and counted in the summary, and GET /api/v1/imports/{id}?rows=issues gives the reason for each. Send larger sets as several imports; a workspace can run up to 10 a minute.

Rate limit headers and error codes

• Every response from a data endpoint now carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a 429 adds Retry-After. The allowance is 5,000 requests a minute per API key, shared by every token issued from that key.
• Every error body now has a code next to the error message, such as validation_failed, not_found or rate_limited. Branch on the code, and show or log the message.
• A request body that is not valid JSON is answered with a JSON 400.

Where to read more

The API reference documents every endpoint, field and error code, and has a console to try each request. Make your first API request goes from a new key to a working call, and Automating links explains when to use the API and when a webhook is the better fit.