Skip to content

Cove API setup

The app reads device and backup data from Cove using a dedicated login. This page creates that login and gives it to the app. No prior API experience needed.

Cove has a dedicated API user type for exactly this. You'll create one, copy its token, and give three things to the app: the login name, the token, and your partner (company) name.

Everything here is done in the browser — the Cove console, then Admin → Cove API in the app. No terminal, no re-deploy.

Already set up and just need to change the token?

Skip to Rotating the API token.

1. Sign in to the Cove Management Console

  1. Go to https://backup.management and sign in with a SuperUser or Administrator account.

2. Create an API user

  1. In the vertical menu, go to Management → Users → API Users.
  2. Click Add API user.
  3. Complete the fields:
    • Customer — choose the top-level partner (your company, e.g. TOTLCOM Inc). Note this exact name; it's your partner name below.
    • Login name — for example api-reporter.
    • Role — the dropdown offers SuperUser, Administrator, Manager, Operator, Supporter. Choose Supporter — it's the most read-only, which is all this app needs (it never changes anything). If a Security Officer checkbox appears, leave it unchecked.
  4. Click Save and continue.
  5. Copy the token — click Copy token to clipboard (or Download token). It is shown only once; if you lose it, delete the API user and recreate it.
  6. Click Copy and close.

Note

API users can use the API but cannot log in to the Console (that's expected). The token acts as the password.

3. Give the credentials to the app

Open the app, go to Admin → Cove API, and click Update credentials. Fill in:

Field What to enter
API URL https://api.backup.management/jsonapi unless Cove has told you otherwise. Must be https.
Partner name The full partner string exactly as Cove displays it — including the account-owner email in parentheses, e.g. TOTLCOM Inc. (dannythompson@totlcom.com). Just the company name (TOTLCOM Inc) fails with "Unknown partner/username or bad password".
API user login name The login name from step 2, e.g. api-reporter.
API token The token you copied. Leave blank to keep the token already saved.

Click Save & verify.

The app runs a real device query against Cove before saving anything. If Cove rejects the credentials you'll see its exact error and nothing is stored — the previous working connection stays in effect. On success the token is encrypted and saved, and the card shows the device count.

Confirm the exact partner string

It's the value shown in the Customer dropdown when you created the API user, or the partner name at the top of the Cove console — copy it verbatim (capitalization, period, spacing, and the (email) part).

That's the whole setup. There is no command line step and no re-deploy — the credentials are stored in the app's database, encrypted, and take effect on the next Cove call.

A brand-new deployment simply has no Cove connection until an admin does this once. Reports won't run before then, which is visible on the dashboard.

About the old COVE_API_USER / COVE_API_PASSWORD secrets

Earlier versions kept the Cove login in Cloudflare Worker secrets, which meant a terminal and a re-deploy to change it. That is no longer how this works — credentials are managed in the app.

The code still reads those secrets as a last-resort fallback if the stored record is ever missing or unreadable, so an old deployment that still has them set won't suddenly break. You don't need to set them on a new deployment, and you don't need to keep them updated on an existing one. See Security & maintenance.

4. Verify it works

  1. Open the app and go to Admin.
  2. Click Test Cove API.
  3. It should report a device count.

If it doesn't work

  • "Unknown partner/username or bad password" — the partner name is the usual culprit. It must include the (owner@email) suffix exactly as Cove shows it.
  • Device count lower than expected, or a permissions error — the Supporter role is too narrow. Recreate the API user with the Manager role (then Administrator if still short) and update the credentials again.
  • "Access denied for security reasons" — the API user can log in but can't read this partner's devices. Check the Customer it was created under.
  • Errors shown on the card are Cove's own words, passed through unchanged.

Rotating the API token

Rotate when someone with access to the token leaves, if you suspect it's been exposed, or once a year as routine hygiene.

Cove shows a token once, at creation, and has no "show me the token again" screen. So rotating means issuing a new one:

  1. In the Cove console, go to Management → Users → API Users.
  2. Create a new API user (e.g. api-reporter-2) with the Supporter role, or delete and recreate the existing one. Copy the new token.
  3. In the app, go to Admin → Cove API → Update credentials.
  4. Enter the new login name and paste the new token. Leave API URL and partner name as they are.
  5. Click Save & verify.
  6. Once it succeeds, delete the old API user in the Cove console.

Do step 6 last. Until the new credentials verify, the old ones are still what the app is using — deleting them first would take reporting down with no way back.

What happens when you save

  • The new credentials are tested against Cove first; a failure changes nothing.
  • The token is encrypted before being written to the database and is never displayed again — the card shows ••••••••.
  • The cached Cove session from the old credentials is discarded immediately, so the change takes effect on the next report rather than up to 15 minutes later.
  • The rotation is recorded in the audit log with who did it and when. The token itself is never logged.

Correcting the partner name or login without a new token

Leave the API token field blank. The app keeps whatever token is already in effect and re-verifies with your corrected details.

Note

On an older deployment that was still running from the Cloudflare secrets, saving here copies that token into the encrypted database record. The Credentials row on the card changes from Deployed secrets to Managed here, and the app stops consulting the secrets.

The "Revert to deployed secrets" button

Update credentials → Revert to deployed secrets deletes the stored credentials so the app falls back to the old COVE_API_USER / COVE_API_PASSWORD Worker secrets.

Only useful if those secrets are still set

On a deployment that has never used them — or where they've since been deleted — this leaves the app with no working Cove credentials, and reports will fail until you enter them again. It exists for older deployments that still have valid secrets to fall back to. If you're not certain they're set and current, don't use it; to change credentials, just save new ones over the top.

Monitoring

The app checks the Cove connection once a day by running a real device query. If it fails:

  • The dashboard shows a warning banner for everyone.
  • Admins get an email.
  • The Admin → Cove API card shows the failure.

This exists so a broken connection surfaces within a day rather than on the 1st of the month when the report silently fails to build.

What the app does with this

  • It calls the Cove JSON-RPC endpoint you configured (by default https://api.backup.management/jsonapi).
  • It signs in for a short-lived session token (cached for 15 minutes), then reads device statistics to build the monthly report.
  • It only ever reads — it never modifies devices, customers, or settings.