Renew the app key

POST/api/v1/device-auth/renew

Access: The key of an app connected through the browser

Renew the API key of a connected app

Bearer key of a browser connection only (client and deviceName set; no body). Within 30 days of its end the key gets a successor of the same client and computer — the same name, its scopes within the client's set, a new term of 365 days — and, in the same transaction, its own term is cut to 10 minutes from now: requests already on their way with it finish, then it answers API_KEY_EXPIRED. Store the new token like a sign-in's and use it from now on. Earlier than that: 409 DEVICE_RENEW_TOO_EARLY, nothing changes. A key renewed before is refused and revoked together with its successor (the answer to the first renewal was lost, or the key leaked): 401 API_KEY_REVOKED, connect again — so send a renewal once and never repeat it on a lost answer. The site session and keys from the key form get 403 DEVICE_KEY_REQUIRED. At most 10 renewals per account per 10 minutes, refused ones included, in addition to the account limit.

Example request

curl -X POST "https://lac.pics/api/v1/device-auth/renew" \
  -H "Authorization: Bearer lac_api_YOUR_KEY"

Responses

200Renewed; store the new tokenDeviceAuthToken
- tokenstringrequiredresponse only
  A Bearer API key, returned once. Keep it like the key form’s tokens (Windows Credential Manager); never in a URL or a log.
  pattern ^lac_api_[A-Za-z0-9_-]{43}$
- keyApiCredentialrequired
  ApiCredential 6 fields
  - idstringrequired
    The file or note id.
  - namestringrequired
    Keys of a connection are named «lacuna для Windows · {deviceName}».
    length 1–100
  - scopesarray of stringrequired
    values: "content:read" "content:write" "content:delete" "account:read"
    1–4 items · unique
  - expiresAtstring · date-timerequired
    After this moment every request answers 401 API_KEY_EXPIRED; connect again. A connection key lives 365 days and renews itself within 30 days of its end (POST /device-auth/renew).
  - clientstringrequiredor null
    App of a key issued by a connection; null for keys made in the key form.
    values: "windows"
  - deviceNamestringrequiredor null
    Null for keys made in the key form.
    length 1–128
- userobjectrequired
  1 field
  - usernamestringrequired
400Invalid trusted client address or malformed JSON before authentication; otherwise invalid request fields.
401API_KEY_EXPIRED, API_KEY_REVOKED (also a key renewed before, which is revoked now with its successor), API_KEY_INVALID, ACCOUNT_BANNED, ACCOUNT_ACCESS_CHANGED, BEARER_REQUIRED, UNAUTHORIZED.BEARER_REQUIRED
403DEVICE_KEY_REQUIRED: a site session or a key from the key form; ORIGIN_FORBIDDEN for a session without the site Origin.DEVICE_KEY_REQUIRED ORIGIN_FORBIDDEN
404ACCOUNT_UNAVAILABLE: the account changed during the request.ACCOUNT_UNAVAILABLE
409DEVICE_RENEW_TOO_EARLY: more than 30 days are left; try again later.DEVICE_RENEW_TOO_EARLY
413JSON body exceeds 1 MB before authentication; upload and quota limits may also refuse this operation.
429RATE_LIMITED: renewal or account request limit.
500Unexpected failure; the key may have been renewed already: do not repeat at once. If the key then stops (API_KEY_EXPIRED), connect again.
503The required rate-limit service is unavailable; access fails closed.

Example response

200 · application/json

{
  "token": "lac_api_NEW_KEY_SHOWN_ONCE",
  "key": {
    "id": "cmf8a1x2k0001q7lh5b2n8r6t",
    "name": "Upload script",
    "scopes": [
      "content:write"
    ],
    "expiresAt": "2026-12-26T09:30:00.000Z",
    "client": null,
    "deviceName": null
  },
  "user": {
    "username": "alex"
  }
}

Error codes

Code	Status	Message
`BEARER_REQUIRED`	401	A Bearer key is required.
`DEVICE_KEY_REQUIRED`	403	Only the key of an app connected through the browser can renew itself.
`ORIGIN_FORBIDDEN`	403	The request origin is not allowed.
`ACCOUNT_UNAVAILABLE`	404	The account is unavailable.
`DEVICE_RENEW_TOO_EARLY`	409	The connection can be renewed within 30 days of its end.

Answers of any method with a key (an invalid or expired key, a missing permission, too many requests) are in Errors.