On this page
Authentication and keys
Every call to Starboard's API needs a key of its own, sent in a header. This page explains what a key is, what it can read, how long it lasts, and the limits on it. To make one and use it, read API quickstart.
What a key is
- A key has the form
sb_read_a1b2c3_orsb_manage_a1b2c3_and a long secret:sb, its right, its id (six letters and numbers), then the secret. - Starboard shows the key once, when it is made. It keeps only the key's SHA-256 fingerprint, so nobody can read the key back, Starboard included.
- Keys are separate from signing in. A key cannot open Starboard's pages, and the browser's sign-in cannot call the API.
- Starboard keeps up to 50 keys. Make one for each app or script, named after it, so you can revoke one without stopping the others.
Send it in the header only
Send the key in the Authorization header, as Bearer, a space, then the key:
curl -s -H "Authorization: Bearer $STARBOARD_KEY" http://192.168.1.20:8095/api/v1/me
A key anywhere else, such as in the address (?key=...), is not read, and the call is refused with
key_needed. Addresses end up in logs and browser history, and a header does not.
Rights and scopes
| Right | Shown as | What it allows |
|---|---|---|
read |
Read only | Read what the API offers |
manage |
Read and manage | Read, and the everyday actions of the pages: approve or decline a request, remove or block a download, pause or resume downloads, build a Library tab again, check for container updates, run a Jellyfin job and send a test alert. With Updates ticked, also update Starboard, Reelix, an app or a plug-in, and roll a plug-in back (API 1.2.0) |
Every address that changes something is a POST, marked Needs: manage in the API reference.
A read key gets 403 right_needed there.
No key, whatever its right, can change settings, keys or plug-in choices, add or remove plug-ins, change the install, take over your apps, restore a backup, use Reelix's admin password, or make Starboard call an address the key gives. The one change to the install a key can make is an update, and only with Updates ticked: to the version Starboard already found, with the same backup, health check and way back as the pages. Those stay with a person signed in to Starboard. Read What the API covers for every page action and its right.
A key's scopes narrow what it reads and does. A key with no scopes reaches everything its right allows. In Settings, Security, What it may read, tick only what the app or script needs. Plug-in keys only read, with the scopes of the read permissions the person approved. Read The plug-in's API key.
| Scope | Shown as | What it covers |
|---|---|---|
apps |
Apps | /apps, /apps/{id}, /status, /health, /uptime, /app-updates, /numbers and /containers; checking for container updates |
downloads |
Downloads | /downloads, /downloads/issues, /transfer, /download-hours and /history; download actions and download hours |
media |
Media | /recent, /playing, /calendar and /extras; running a Jellyfin or Audiobookshelf job |
library |
Library | /library, /library/search and /library/status; building a tab again |
requests |
Requests | /requests; approving and declining |
system |
System | /system, /system/history and /version; sending a test alert |
logs |
Logs | /logs: Starboard's log, with addresses, names and keys taken out, and /logs/limits. With Read and manage, also change the log limits and delete all logs. Only a key with logs ticked has it: a key with no scopes does not |
updates |
Updates | /updates, /updates/runs and /updates/runs/{id}; with Read and manage, starting an update and rolling a plug-in back. Only a key with updates ticked has it: a key with no scopes does not. API 1.2.0 |
/api/v1/ and /me work with any key. /openapi.json needs no key. /events works with any key, and each event
reaches only the keys whose scopes cover it.
A key asking for something outside its scopes gets 404 not_found, not 403,
so a key cannot find out what exists beyond what it may read.
Whatever the key, the API never sends a secret: an app's API key shows only as api_key_set, true or false,
and the VPN's own internet address is left out.
Changes, safely
- Send the body as JSON, of up to 64 KB, such as
{"action": "pause"}. A larger one gets413too_large. - Send an
Idempotency-Keyheader, such as a new random value for each action, to make a retry safe: the same key and value within 24 hours gets the first answer again, withIdempotent-Replayed: true, and nothing is done twice. - Work that takes a while, such as building a Library tab, answers
202withstatus, the address to read to find out how it went. - Every change made with a key is written to the audit log with the key's id, the address and the answer.
Expiry
When you make a key, Ends sets when it stops working: In 90 days, In a year or Never. The list of
keys shows when each one ends. After that, it gets key_needed. Make a new one to
carry on.
Revoke a key
Go to Settings, then Security, then API keys, and select Revoke beside the key. Anything using it stops working at once. Changing your password or signing out everywhere does not stop a key: revoke it.
The list shows when each key was last used, to the nearest minute, so you can find keys nothing uses any more.
Rate limits
- Each key can make up to 120 requests a minute. Past that, the answer is
429rate_limited, withRetry-After: the seconds to wait. - Every answer has a
RateLimitheader saying how many requests are left, such as"per-key";r=118;t=0, and aRateLimit-Policyheader,"per-key";q=120;w=60. - Wrong keys count towards the same lockout as wrong passwords, for each address. Too many, and the address gets
429too_many_attemptsfor 15 minutes.
Every request counts, a 304 included. To stay well inside the limit, ask no more often than the answer's
Cache-Control says it stays fresh, and use If-None-Match with the last ETag so an answer that has not changed
has no body to read. Read API quickstart.
The audit log
Starboard writes a line to its audit log, data/logs/audit.jsonl, each time a key is made or revoked, each time
a key changes something (api_write, with the key's id, the address and the answer's status), and each time a wrong
key is refused, with the address it came from. Plug-ins being added, updated, rolled back, activated
and removed are written there too. The log never holds a key or a password. It keeps 5 files of about 1 MB each, and counts towards the log limits in
Settings, General, Logs and feedback: its older files go with the oldest days, and Delete all logs empties it (the
delete itself is its next line).
Keep keys safe
- Treat a key like a password. Keep it in an environment variable or a file only you can read, not in your code.
- Do not paste a key into a chat, a forum or an AI assistant. If one gets out, revoke it and make another.
- Starboard's API answers over plain
httpon your home network. To use it away from home, read Use Starboard away from home safely.
Find out more
This page on GitHub, where the help is written.