Glossary

The words these pages use with a precise meaning. Pages link a term here on its first use. P always stands for /tenants/:tenant_id/applications/:application_id.

Access entry: A grant on one folder or file: a principal (a user, a role, or everyone in the application) and the actions it gets.
Action: What a principal may do with one file or folder: view, download, edit, share, delete or approve.
Application-managed folder: A folder a machine client of the application marked managed. It and everything below it are read-only for people; only the application's machine clients change them, and the tenant owner can release the mark in an emergency.
Audience: What a token's aud claim says: files-api. The service checks it; you never send it.
Backend client: A confidential OAuth client of your application that runs on your server and gets machine tokens with client_credentials. Its secret never reaches a browser or an app.
Context: A tenant plus a tenant application, named in the URL of every call as /tenants/:tenant_id/applications/:application_id (written P on this site).
External reference: external_ref: your own id on a file or folder, such as post:123. A list and search filter; not unique.
Identity Server: The CCS Identity Server: users, sign-in, tenants, applications, roles, clients, scopes and tokens. The File Service owns none of them.
Inheritance: A file or folder sees its own entries plus its parent's, until one of them sets inherit: false.
Job: Work the service finishes after answering 202 with a job_id, such as copying or trashing a large folder. Read it on GET P/jobs/:job_id.
Legal hold: A hold on one file, with a reason and an optional end, that keeps its bytes: while it is in force nobody can purge the file or delete its versions, and the trash keeps it. Placed and released with files.manage.
Machine token: A token your backend client gets for itself, with files:manage, files:read or files:config.manage.
Multipart upload: An upload in parts, each PUT to its own URL, used above the single PUT size. Parts can be retried and resumed.
Owner: The user a file or folder belongs to (owner_id). The owner holds the application's owner actions on it.
Permission key: One of the eleven files.* keys the tenant owner maps onto roles per application, for example files.view or files.settings.manage.
Platform administrator: A user the Identity Server reports with the platform_admin role. Sets the tenants' quotas and ceilings.
Platform application: A Central Code Station service registered on the Identity Server, such as Files, Chat or Notifications. Never one of your applications.
Quarantine: What happens to a file the malware scan found infected: state: quarantined, never served again, its renditions, public copy and share links removed.
Quota: The bytes a tenant or application may store. A ticket that does not fit is refused before any byte moves.
Rendition: A derived copy the service makes after upload, such as thumbnail, preview or a video's poster.
Resource identifier: The address you send as resource= in a token request: https://files.centralcodestation.com/api. Not the audience.
Revision: A counter on every file and folder that grows with every change. Send it as If-Match to refuse a stale write.
Scope: An OAuth permission on the token: files:access for users; files:manage, files:read and files:config.manage for backend clients.
Share link: A URL with a secret token that lets anyone who has it view, or view and download, one file or folder, with an expiry and an optional password.
Signed URL: A short-lived address that carries its own authorisation for one object. Uploads PUT to one; downloads and previews GET one. No token is sent.
Storage account: A place where files are stored: the platform storage (default), or a tenant's own store, set up by a platform administrator. Moving a tenant between accounts keeps every file id.
Taxonomy: A managed list of values for category or department. When enforced, only listed values are accepted.
Tenant: An organisation on the Identity Server. Users are members of one or more tenants; every file belongs to exactly one tenant.
Tenant application: One of your products inside a tenant, for example a social app or a document library. Files, folders and settings live inside it.
Tenant owner: The Identity Server role that holds every permission in every application of the tenant, and the only one that can hand out files.permissions.manage.
Token exchange: RFC 8693: your backend trades the user's token for your API for a File Service token of the same user.
Upload policy: A named set of allowed types and a size cap in the application's settings, chosen per ticket with policy.
Upload ticket: What POST P/uploads answers: the new file_id and the signed URL, or part URLs, the bytes go to.
User token: A token that acts as a signed-in user, with files:access. Your backend gets one by token exchange.
Version: One immutable upload of a file. A new upload to the same file adds a version and makes it current.
Visibility: A shortcut over the entries: private (the entries decide), application (every member may view and download) or public (anyone with the link).
Webhook: An HTTPS endpoint of your backend that receives the file events of one application as signed POST requests, with retries. Set with PUT P/webhooks.