# 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](/documentation/license-auto-renew).

> **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:

```bash
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

- [Automatic License Renewal](/documentation/license-auto-renew)
- [License and Tiers](/documentation/license)

---
Source: https://selfdochub.com/documentation/auto-renew-tokens
