Auto Renew Tokens

An Auto Renew token lets an installation of SelfDocHub fetch its renewed license by itself, without anyone signing in to this site and downloading a file. This page explains how to create and manage tokens in the admin dashboard. To use a token in the application, see Automatic License Renewal.

Roles: The Auto Renew page of the dashboard is available to business owners and administrators of the portal. A business owner sees the tokens of their own businesses.

How it works#

  1. You create a token on the Auto Renew page of the dashboard. A token belongs to one business.
  2. You enter the token in the Auto renew block of the License page of your installation.
  3. Once an hour the installation sends the token, its device ID and the created_at date of its current license.json to the license server.
  4. If the license server holds a newer file for that device ID, for example after the subscription was renewed, the installation receives it and installs it.

When a subscription is renewed, the licenses of the business are extended to the end of the new period plus a short grace period (24 hours by default), and the business owners get the email "Your licenses were renewed". Installations that use a token then pick the extended license up within the hour.

Creating a token#

  1. Open Auto Renew in the dashboard and click New Token.
  2. Enter a Name that tells you where the token is used, for example Production installations.
  3. Administrators enter the Business ID. A business owner with several businesses picks one; with a single business it is chosen automatically.
  4. Click Generate, then Copy. A token looks like sdhr_ followed by 48 hexadecimal characters.
  5. Optionally limit the token to specific licenses (see below).
  6. Click Create.

Warning: Copy the token before you click Create. Only a hash of it is stored, so it can never be shown again. If you lose it, regenerate the token and update the installations.

Which licenses a token covers#

By default a token applies to all licenses of the business, including licenses issued later. To restrict it, add the device IDs of the licenses it may act on. A device ID is the UUID shown on the License page of an installation or printed by docs-hub --print-device-id. A token that is limited to some device IDs is refused for any other installation.

Managing tokens#

The list shows the ID, the name, how many licenses the token covers, the business (for administrators) and when it was Last used. You can filter it by ID, name, business ID and device ID.

Action What it does
Edit Changes the name and the list of licenses. The token itself cannot be changed here.
Regenerate Creates a new secret and shows it once. The old token stops working immediately, so every installation that uses it must be updated.
Delete Removes the token. Installations that use it can no longer renew their licenses. The licenses themselves are not affected.

Use one token for a group of installations that should be renewed together, or one token per installation to be able to revoke them separately.

The endpoint#

Installations call this endpoint. You only need it to check a token by hand:

curl -X POST https://admin.selfdochub.com/api/v1/licenses/auto-renew \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"device_id": "<device id>", "created_at": "<created_at of the license file>"}'
Answer Meaning
created (201) The installation had no license, and a new one was issued because the subscription still has quota. The signed file is in license.
updated (200) The server holds a newer license; the complete signed file is in license.
up_to_date (200) Nothing to do.
401 The token is missing or invalid.
403 The token is not valid for this device ID.
422 The request is invalid, or there is no subscription or quota to issue a license.

The endpoint accepts up to 60 requests per minute.

Next steps#

Last updated: