Manage your API access
Settings → API access: the state of each gate, its databases, its month's usage, what Filarr saw, and the gestures pause, replace the token, remove and revoke.
On this page
Documentation sections
Settings → API access lists the gates that read your databases. Each has its own token: cutting one off does not touch the others. The screen needs a Filarr account signed in on this profile. To create an access: ··· on a database, then Open to an API… (Open a database to an API).
At the top, a badge says how many accesses are open out of how many your plan allows.
The state of an access
| state | what it means |
|---|---|
| live | the gate synced recently |
| never seen | the gate has not synced yet: the token has not been used |
| silent N h, silent N d | nothing for that long: the gate is stopped, offline, or can no longer reach Filarr |
| paused | you paused it |
| paused by the plan | your plan went down: the accesses beyond its limit are paused, the most recent first |
| expired, revoked | the token is refused for good |
What an access shows
- Token: only its beginning, enough to recognise it. The token itself is never shown again.
- Gate: when it was last seen, and its version.
- Databases: each database opened, in read or in read and write.
- Expires: the expiry date, or "never". Change… changes it.
- Allowed addresses: the IP addresses from which Filarr accepts the token, or "any address" (the list is included from Pro).
- This month, for this access: the month's sync requests, the month's downloaded volume, today's commits, against your plan's limits. At 80 %, then at 100 %, a notice shows. Reads served by the gate are never counted: only what goes through Filarr is.
- What Filarr saw: the access's log, kept a number of days that depends on the plan. You read there: access created, token presented for the first time, token refused (with the reason), accepted commits, keys changed for a database (with the generation), keys re-sealed, database opened or removed, quota reached, paused, reopened, token replaced, revoked. Encrypted blocks and accepted commits, never their content: that is all that goes through Filarr. Older events goes back in time.
The gestures
| gesture | what happens |
|---|---|
| Rename | the access's name changes; nothing else |
| Pause | Filarr refuses the token; the gate keeps its copy and keeps serving it. Reopen starts it again |
| Replace the token | a new token, shown once; the old one is refused at once, and the gate erases its copy until you give it the new one |
| Remove a database (Remove and change its keys) | the database leaves the access, and its keys change: the old token will not be able to read anything written afterwards in that database. The other databases do not move |
| Revoke (Revoke and change the keys) | the gate loses access at once. Its databases change keys (next generation): the old token will not be able to read anything written afterwards. What it already copied stays on its machine: erase it there if the machine is no longer trusted |
Replacing the token does not change the databases' keys; revoking does. If a token leaked, revoke the access and create a new one.
Changing keys needs the database's vault open and the server reachable. Otherwise, the screen says the keys of those databases will change as soon as that is the case, and one of your devices does it at its next opening.
When the plan goes down
The accesses beyond the limit are paused, the most recent first, and a database in read and write can no longer be written if the new plan has no writes. Nothing is deleted: after an upgrade, reopen the paused accesses yourself.
Learn more
- The tutorial "Revoke an access, and react to a leak" of the gate's repository: github.com/filarr-work/filarr-gate.
- Gate troubleshooting