Accounts and the access model
Key levels, ownership, public objects and the portal.
Reference
Access to BioStor is organised around accounts, each with an API key and an access level, and around ownership of objects. There are no per-object permissions: if several people or services need the same access, they share an account. This page describes the four levels, what ownership allows, how an object is made public, how the workbench reaches files for you, and how the portal's own login works.
Access levels
| Level | Account type | Reads | Writes |
|---|---|---|---|
| 0 | Public key | Objects marked public | Nothing; cannot sign in to the portal |
| 1 | Manager | Its own objects and public objects | Its own objects |
| 5 | System (integrations such as the workbench) | Everything | Everything |
| 9 | Administrator | Everything | Everything, plus the admin console |
An API key is sent in the api-key header. To write, or to read an object that is not public, the key must belong to an active, unexpired account at level 1 or above. Administrators create accounts, set levels, rotate and reveal keys, set key expiry dates, deactivate and reactivate accounts, and create or revoke an account's webhook secret; every one of these actions is audited.
Ownership
The account that uploads an object owns it. Owners can replace the file, update its metadata and delete it within a control period, which is 30 days from creation by default; system and administrator accounts can do these things on any object. Ownership can be handed to another active manager, system or administrator account, up to 100,000 objects in one request. Hand-off is the intended way to onboard data with one account and then give it to the team that will manage it; each move is audited. In the portal, select rows on the Objects page (or Select all N matching) and choose Hand off to.
Reading objects
Opening one object (GET /api/objects/{id}, its metadata, or the bulk presign resolver) follows one rule: a public object opens with any key or none; any other object opens only for its owner or a system or administrator key. An object the caller may not read is reported as not found, never as forbidden, so object identifiers do not reveal whether something exists. Listings and searches (per-type lists, counts, recent objects, profile listings) require a valid key of any level and return only what that key may read.
Public objects
An object is private by default. Its owner, or a system or administrator account, can mark it public at upload with is_public, or later with PUT /api/objects/{id}/visibility; both directions are audited. A public object can be read with a level-0 public key, or with no key at all. Public keys are ordinary accounts: give each external consumer its own, with an expiry date, so it can be rotated or revoked independently.
How the workbench accesses files for you
You never hold a BioStor key. The workbench has a single system-level account, which it uses to search and fetch objects on your behalf. When a page shows an image, a trace graph or a document, the workbench resolves the object with its own key and serves it to your browser through a link that is bound to your workbench session and signed, so the link is useless outside that session. Which records and files you can see is decided by the workbench's own project and dataset sharing, not by BioStor accounts. See Security between services and Evidence files.
The analysis service uses its own system-level account for job packages and results.
The portal login
The BioStor portal has its own sign-in, separate from the workbench. An account holder signs in with a username and password, or with their API key; public (level 0) keys cannot sign in. Every attempt is recorded, and after five failed attempts for a username within 15 minutes further attempts are refused until the window passes. Administrators set and reset passwords from Admin → Users.
Inside the portal, administrators see every object. Any other account, including a system account, sees only the objects it owns, and does not see other accounts' public objects.
Good to know
- An account's access level is read at sign-in and kept for the session, so a change made by an administrator applies at the account's next portal login.
- The portal shows a narrower view than the API gives a system account: the API lets a system key read everything, the portal shows that account its own uploads only.
- Deleting an object is allowed for the owner within the control period or for a system or administrator key; the portal additionally limits deletion to
readyobjects and to objects still in processing (see Object lifecycle and statuses).