Settings reference

Each application has one set of storage settings. Administrators change them on the console’s Settings page; a backend reads and changes them with files:config.manage. Defaults and ranges below come from the service itself.

Permission: files.settings.manageMachine scope: files:config.manage

Reading and changing

Route	Does
GET P/settings	The application’s settings, every key
PUT P/settings	Merge: send only the keys that change. Every invalid value is listed at once in a 400 invalid_request
GET P/settings/public	What an uploader needs (allowed types, sizes, named policies, public_visibility_enabled, approvals_enabled, share_links_enabled, single_put_max_bytes): any member, any machine scope

Settings changes are rate limited and audited (settings.updated, with the values before and after). A value the tenant does not allow is refused: public as default visibility without public files answers public_visibility_disabled; the effective sizes and switches never exceed the tenant’s ceilings set by a platform administrator.

settings.ts

import { FilesClient } from '@central-code-station/ccs-files-client';
import { files } from './files-client';

// What your UI needs before it offers an upload: allowed types and sizes, the named policies. Any machine scope.
export async function uploadRules() {
  const rules = await files.settings.public();
  return { types: rules.allowed_types, maxBytes: rules.max_file_size_bytes, policies: rules.upload_policies };
}

// A deployment script with its own client (files:config.manage) sets the application's settings.
const admin = new FilesClient({
  issuerUrl: process.env.CCS_ISSUER_URL!,
  clientId: process.env.CCS_FILES_CONFIG_CLIENT_ID!,
  clientSecret: process.env.CCS_FILES_CONFIG_CLIENT_SECRET!,
  apiUrl: process.env.FILES_API_URL!,
  resource: process.env.FILES_API_RESOURCE!,
  tenantId: process.env.CCS_TENANT_ID,
  applicationId: process.env.CCS_APPLICATION_ID,
  scope: 'files:config.manage',
});

export async function configure() {
  await admin.settings.update({
    allowed_types: ['image/*', 'video/*', 'application/pdf'],
    upload_policies: { avatar: { allowed_types: ['image/*'], max_file_size_bytes: 5 * 1024 * 1024 } },
    owner_actions: ['view', 'download', 'delete'], // your backend is the only one that edits
  });
}

The keys

Key	Default	Allowed	Meaning
quota_bytes	null		The application's own quota in bytes; null uses what the tenant quota leaves. It must fit in the tenant quota minus the other applications' quotas.
max_file_size_bytes	2 GiB	1 to the size ceiling	The largest file a ticket accepts. Never above the tenant's ceiling or the platform maximum.
allowed_types	['*']		The MIME types a ticket accepts: exact types, families such as image/*, or * for everything. Checked on the declared type at the ticket and on the detected type after upload.
upload_policies	{}		Named overrides of allowed_types and max_file_size_bytes, selected per ticket with policy (for example a chat policy with images and videos only). A named policy only narrows the application's own.
type_mismatch_policy	'reject'	reject, trust_detected, trust_declared	What happens when the bytes are not the declared type: reject refuses the file, trust_detected keeps it with the detected type, trust_declared keeps the declared type.
scan_policy	block_until_clean (off on a service that runs without malware scanning, such as a local development setup)	block_until_clean, async, off	When a file becomes downloadable relative to the malware scan: block_until_clean (nothing is served before the scan is clean), async (served at once, quarantined if the scan finds malware) or off.
scan_failed_policy	'block'	block, allow	What a file whose scan could not finish gets: block (never served, 409 scan_pending) or allow (served as if clean).
scan_oversize_policy	'allow'	allow, block	What a file too large to scan gets: allow (served unscanned) or block (never served, 409 scan_pending).
image_metadata	'strip'	strip, keep	strip rewrites images without their camera metadata (EXIF, XMP, IPTC, location included), orientation applied; keep leaves them unchanged.
renditions_enabled	true		Whether images, videos and PDFs get thumbnails, previews and the video's MP4 renditions.
text_extraction_enabled	true		Whether documents get their text extracted for content search (in=content). Off: new versions are not searchable by their text.
public_visibility_enabled	false		Whether files may be made public (a stable URL anyone with the link can open). Also needs the tenant to allow it.
default_visibility	'private'		The visibility of a new file when the ticket does not name one.
owner_actions	['view','download','edit','share','delete']		What the owner of a file or folder may do with it, whatever the entries say.
owner_can_purge	false		Whether owners may purge their own files from the trash (otherwise only files.manage).
approvals_enabled	false		Whether the approval status (draft, in_review, approved, rejected, archived) is in use; the console hides it otherwise.
share_links_enabled	true		Whether share links may be created. Also needs the tenant to allow them and share_link_max_days above 0.
share_link_max_days	90	0 to 365	The longest expiry a share link may have; 0 switches share links off.
share_base_url	null		Your own host for share links (an https URL); null uses the service's.
trash_retention_days	30	0 to 365	How long trashed items stay restorable before they are purged; 0 purges at once.
max_versions	10	1 to 100	How many versions of a file are kept; older ones are pruned (never the current or a pinned one).
version_retention_days	365	1 to 3,650	How long a non-current version is kept.
checkout_max_days	7	1 to 30	The longest a check-out may hold a file. Check-out is coming; the value is stored already.
download_url_ttl_seconds	15 minutes	60 to 86,400	How long minted download and preview URLs live.
updated_at			When the settings last changed (read-only).
updated_by			Who changed them last (read-only).

Managed lists

categories and departments are separate: GET P/taxonomies/:name and PUT P/taxonomies/:name with { values: [{ value, label, active }], enforced }. When enforced is true, category and department accept only active values (taxonomy_value_invalid).