Skip to main content

API key permissions

Each API key holds a list of Permissions and an optional Instance limit. You set both in Settings → API keys when you create a key. To change them later, click the edit button on the key. An edit applies on the next request of the key, and the key itself does not change.

A key must hold at least one Permission. POST /api/api-keys returns 400 to a request with no Permission list.

Keys that existed before the upgrade to this feature hold every Permission and have no Instance limit. Edit each of these keys to remove the access that the key does not need.

When authentication is disabled, qui ignores API keys. Permissions and Instance limits then do not restrict a request.

Levels​

A Permission is one area and one level, for example Torrents: read. There are three levels:

  • read shows data. It does not start work.
  • run starts work that is already set up. It does not include read, because settings hold credentials.
  • write changes data. It includes read and run.

The level is a property of the route. It does not come from the HTTP method. For example, POST /api/instances/{instanceID}/torrents/check-duplicates needs Torrents: read.

Areas​

Each area offers only the levels in this table.

Areareadrunwrite
InstancesList instances, preferences, capabilities, transfer informationNot offeredAdd, edit, and delete instances, change preferences, test a connection
TorrentsList torrents, read their details, download a content file, read the transfer historyNot offeredAdd, change, and delete torrents, export a .torrent file, download a .torrent file from the torrent creator
Cross-seedRead settings, status, routes, the blocklist, and run history, search for matches, analyze a torrent, read match proposalsThe autobrr apply, the webhook check, the season-pack check and apply, start and stop a runChange settings, routes, and the blocklist, apply search results, apply a manual match, assemble a pack by hand
Dir ScanRead settings, directories, status, and runsThe webhook scan, start and stop a scanChange settings and directories
AutomationsRead rules and activity, preview a ruleApply now, apply one rule, dry runCreate, edit, reorder, and delete rules, delete activity
RSSRead feeds, rules, and eventsRefresh a feed, reprocess rulesChange feeds, folders, and rules
BackupsRead settings, runs, and manifests, preview a restoreStart a backupChange settings, import a manifest, restore, delete runs, download a run, download a torrent from a run
Orphan scanRead settings and runsStart and cancel a scanChange settings, confirm a deletion
External programsList programsRun a programNot offered. See Browser-only routes
IndexersRead indexers and their health, searchNot offeredAdd, edit, delete, and test indexers, change the search cache settings
ArrRead Arr instances, resolve an external IDNot offeredAdd, edit, delete, and test Arr instances
NotificationsRead targets and eventsNot offeredAdd, edit, delete, and test targets
SettingsRead client settings, tracker customizations, the dashboard, filter views, and the database shrink statusNot offeredChange these items, the theme settings, the custom themes, and the Statistics settings. Dismiss the result of a database shrink and the "Shrink failed" notice
LogsRead log settings, exclusions, files, and the log streamNot offeredChange log settings and exclusions, except the log file path. See Browser-only routes
SystemApplication informationNot offeredNot offered

A .torrent file and a backup hold tracker passkeys, so their downloads need write. A key without Torrents: write also gets tracker URLs with the passkey hidden.

Each key can reach these routes with any Permission: the current user, tracker icons, peer-client icons, the theme list, the custom theme list, the version, the latest version, and the event-only stream. A torrent stream needs Torrents: read.

Instance limit​

An Instance limit is a list of instances that the key can reach. A key with no Instance limit reaches every instance, also the ones that you add later.

A key with an Instance limit follows these rules:

  • It reaches a route under an instance only when that instance is in the limit.
  • It sees only the instances in the limit in GET /api/instances.
  • It gets a 403 from cross-seed and Dir Scan routes, and from routes that span instances. These are the cross-instance torrent list, the torrent archive export, the delete-cross-seeds check, the instance order, the list of instances with transfer history, the Statistics settings, and the database shrink status. These routes do not narrow their results to the limit.
  • It gets a 403 when a stream asks for another instance. The check also applies when an open stream adds an instance.
  • It gets a 403 when an automation exports to another instance.

The create and edit dialogs grey out the Cross-seed and Dir Scan rows when you pick an instance. qui does not save a Permission on a greyed-out row.

A new instance does not join an existing limit. A deleted instance stays in the stored list and matches nothing. If a limit holds only deleted instances, the key reaches no instance, and Settings shows "No instances" for it.

Browser-only routes​

A Browser-only route refuses every API key, also a key that holds every Permission. It accepts only a signed-in browser.

When authentication is disabled, qui ignores API keys, so this refusal does not apply. API key management, change password, and logout still return 403 Endpoint disabled when authentication is disabled. The other Browser-only routes accept the request.

The Browser-only routes are:

  • API key management
  • Client proxy API key management
  • System update and restart, and the request to shrink the database file
  • The SSH credential and host-key routes of an instance
  • Change password and logout
  • The license routes
  • External program create, update, and delete
  • The Transfer routes under /api/transfers
  • The Share routes under /api/shares, also the Share settings and the download of the .torrent file of a Share

The log file path is a Browser-only setting on a route that API keys can use. PUT /api/log-settings accepts a key with Logs: write for Log level, max size, and max backups. It returns 403 API key not allowed; use the web UI and changes nothing when a key sends a path that differs from the current one. A key can send the current path back unchanged.

403 messages​

A key that cannot use a route gets one of these 403 bodies:

BodyMeaningFix
API key needs Torrents: writeThe key does not hold this Permission.Add the Permission to the key.
API key cannot reach instance 2The Instance limit of the key does not hold this instance.Change the Instance limit, or change the request.
API key with an instance limit cannot use this routeThis is a cross-seed or Dir Scan route, or a route that spans instances.Use a key with no Instance limit.
API key not allowed; use the web UIThis is a Browser-only route, or the request changes the log file path.Use the web UI. No Permission allows this.

These checks apply only to API keys. A signed-in browser has full access, and a 403 from a key check does not sign you out.

Permissions for integrations​

IntegrationPermission
autobrr cross-seedCross-seed: run
Season packs, check and applyCross-seed: run
Season packs, run listCross-seed: read
Dir Scan webhookDir Scan: run
External programs, run a programExternal programs: run
A dashboard that shows torrentsTorrents: read. Add Instances: read if the dashboard lists the instances

The cross-seed and Dir Scan integrations need a key with no Instance limit.