Open a database to an API

An access opens the databases you choose, and only them, to a gate that serves them to your software. You create it from the desktop app or the web; the mobile app sends you there.

Every plan can open a database to an API. The plan sets how many accesses you can have, how many databases one access opens, whether writes and live changes are included (from Solo) and whether you can restrict the addresses that sync (from Pro). The form shows your limits, and plans details them.

Before you start

• A Filarr account signed in on this profile, the app unlocked.
• A database in a note. You must own it; for a vault's database, be the vault's owner or an admin.
• A database backed by a folder (its rows are files) or kept in your own storage cannot be opened to an API. A small database first moves to Filarr's large database storage, whatever its size; this changes nothing for you.

Open the form

On the database, click ··· then Open to an API….

The item is greyed out, with the reason, when the note is read only, when no account is signed in, when large databases are switched off on this device, or when you are not the vault's owner or an admin. If the form shows Not available yet, API access is not open for your account yet.

Fill it in

• Access name: who will use it ("ERP Atelier", "Website"). It names the gate in Filarr.
• Databases opened: the database you started from is ticked; tick others to open them with the same token. For each one, choose Read or Read and write (writing also needs a plan that includes it).
• Slugs: the name of each database and each view in the gate's API, proposed from their titles (clients, clients-actifs). They can only be chosen now. Afterwards they never change, even if you rename the database or a view: the software that uses them does not break. A view created later gets its slug when it is published.
• Linked databases left closed: if a database has a relation to a database you did not tick, the form names it. The gate never reads a database it was not given: those relations will give raw ids and their rollups will be empty. Open it too adds it.
• Expires: in 6 months, in 1 year, or never. At the expiry, Filarr refuses the token and the gate erases its copy.
• Addresses allowed to sync (from Pro): Filarr refuses the token from any other IP address. Separate addresses or ranges with commas (203.0.113.7, 10.0.4.0/24): the public address of the machine that runs the gate.

Click Create the access.

Keep the token

Filarr shows the token only once. Copy it where the gate will read it: your password manager, a secret of your server or of your Cloudflare account. Filarr only keeps a fingerprint of it: if it is lost, it can be replaced, not recovered. Whoever holds it reads the databases it opens: treat it like a password.

The screen offers four ways to install the gate (on this computer, Docker, in your code, Cloudflare) and links to the documentation of the gate's repository, which describes them step by step. Then click I saved the token. That button is the only way out of this screen: a window closed by mistake would lose the token.

If some older blocks of the database use a key this device no longer holds, the screen warns you: the gate will report them as "missing key" until a device that holds it opens Filarr.

Next

As soon as it first syncs, the gate appears in Settings → API access, with its version, its address and when it was last seen: see Manage your API access. The tutorial "Open a database to an API" of the gate's repository shows the rest, on the gate's side: github.com/filarr-work/filarr-gate.

If it does not work

• "Only the owner or an admin of the vault can open its databases": ask the vault's owner.
• "Your plan allows … open access(es)": pause or revoke an access in Settings → API access.
• The gate reports key_missing for a database: open Filarr on a device that holds its key, unlocked; the keys are re-sealed.
• See also Gate troubleshooting.