Skip to main content

Script against the API with a token

A personal API token lets a script or another computer call Hoserva's API without signing in as a person. This page creates a token, then uses it to list your disks. Create one token for each script, so you can revoke it on its own.

Before you start​

  • You are signed in to the web interface as an admin, or you have a shell on the Hoserva server as root or as a member of the hoserva group.
  • Your computer can reach the server on port 8008. By default Hoserva accepts connections only from private network addresses.
  • curl and jq are installed on the computer that runs the script.

Create a token​

  1. Open Users.
  2. In the Personal API tokens card, select Create token.
  3. Under Account, choose the account the token belongs to.
  4. Enter a Token name that says what the token is for, such as disk-report.
  5. Under Scope, choose Viewer. A viewer token can read state but cannot change anything. Choose Admin only for a script that has to change settings.
  6. Select Create token.
  7. Copy the value shown under Token created.
The token is shown once

Copy the token now. Hoserva stores only a hash of it, so it cannot show the value again. If you lose it, revoke the token and create a new one. Treat the token like a password: anyone who has it can call the API with its scope.

A token can have a narrower scope than its account, never a wider one. An admin can hand a script a viewer token to limit what the script can do. An account with only SMB or NFS access cannot have a token.

List your disks with the token​

The script reads the token from a variable, so the token never appears in the script or in your shell history.

  1. Store the token and the server's name in your shell. Paste the token when read waits for it. Nothing is echoed.

    read -r -s HOSERVA_TOKEN
    export HOSERVA_TOKEN
    export HOSERVA_HOST=nas.local

    Replace nas.local with the name or address of your server.

  2. Save this script as list-disks.sh:

    list-disks.sh
    #!/usr/bin/env bash
    set -euo pipefail

    curl --silent --show-error --fail \
      --header "Authorization: Bearer $HOSERVA_TOKEN" \
      "https://$HOSERVA_HOST:8008/api/v1/disks" \
      | jq -r '.disks[] | [.device, "\(.sizeBytes / 1e12 * 10 | round / 10) TB", (.model // "unknown")] | @tsv'

  3. Run it:

    bash list-disks.sh
    Output
    /dev/sdb	4 TB	WDC WD40EFRX
    /dev/sdh	1 TB	Samsung SSD 870 EVO 1TB

The script prints one line per disk: the device, its size and its model. Your output lists your own disks.

--fail makes curl exit with an error on any non-success status, so set -e stops the script instead of passing an error message to jq.

curl checks the server's certificate, and with Hoserva's default self-signed certificate that check fails. Give Hoserva a certificate your computer trusts: issue a Let's Encrypt certificate (see Exposing services safely), or save a copy of the self-signed certificate and add --cacert with its path to the curl line. For a one-off test on a network you control, you can add --insecure to the curl line, which skips the check. Do not keep it in a script you reuse: anyone who can intercept the connection could then pose as your server and receive the token.

The operation behind the call is List disks. Every operation page in the API reference shows the role it needs and an example request in the same form.

Use the token with the command-line tool​

The hoserva command-line tool can also run from another computer. It reads the same token from HOSERVA_TOKEN:

hoserva --host "$HOSERVA_HOST" disk list

That works when the server presents a certificate your computer trusts, such as one from Let's Encrypt, and you address the server by its domain name. With the default self-signed certificate, pin it by its fingerprint. On the Hoserva server, read the fingerprint:

openssl x509 -noout -fingerprint -sha256 -in /var/lib/hoserva/tls/hoserva.crt | cut -d= -f2

Then pass the value it prints with --tls-fingerprint, or set HOSERVA_TLS_FINGERPRINT:

hoserva --host "$HOSERVA_HOST" --tls-fingerprint "AB:CD:…" disk list

hoserva checks the fingerprint before it sends the token, and refuses to connect to a server whose certificate differs. When you regenerate the self-signed certificate, read the fingerprint again and update the value you pass.

--insecure-skip-tls-verify skips the check entirely, so the token goes to whoever answers. Use it only for a one-off test on a network you control, and never together with --tls-fingerprint.

Revoke a token​

Revoke a token when a script is retired or the token may have leaked. A revoked token stops working at once.

  1. Open Users.
  2. In the Personal API tokens card, find the token.
  3. Select Revoke and confirm the prompt.

A call returns an error​

What you seeLikely causeWhat to do
curl reports a certificate problemHoserva's default certificate is self-signedTrust the certificate on your computer, or add --cacert with a saved copy of it. Use --insecure only for a one-off test on a network you control
401 with the code unauthorizedThe token is wrong, was revoked, or the header is missingCheck HOSERVA_TOKEN, and create a new token if you cannot find the value
403 with the code forbiddenThe token's scope is too narrow for the operationCreate a token with the Admin scope, if the script really needs it
The connection times out or is refusedYour computer is outside the networks Hoserva acceptsSee Exposing services safely

Next steps​