SecBoost API v1 authentication

API v1 uses Laravel Sanctum personal access tokens issued to an active human SecBoost user through the authenticated, credential-confirmed token page. Send secrets only as HTTPS bearer headers. Bearer credentials cannot issue credentials or administer users, membership, teams, roles or authentication.

Authority is the intersection of the credential's selected application permissions, its execution mode and type/target boundary, the actor's current permissions and access, and the operation's normal policy, workflow and lifecycle checks. Neither role names, global staff status nor the selected UI project bypass these checks. Removing access or permission takes effect on subsequent requests and protected queued-work checkpoints. There is no separate API permission vocabulary.

Execution mode and lifetime

Every new credential explicitly stores read_only, defaulting to true. Read-only credentials can perform permitted reads but cannot change resources, generate documents, comment/claim/release tasks, import provider data or publish. Selecting editing, management or approval permissions never disables read-only execution. Disable the checkbox explicitly for mutation-enabled automation. A permission named view-tasks can permit ordinary task actions in the application, but those API actions still require mutation-enabled execution.

These are the default configured maximum lifetimes. Choose the shortest practical expiry. Missing mode, malformed binding, empty, unknown, retired, mixed, wildcard or out-of-type grants fail closed. New issuance rejects them rather than dropping unsupported selections. Secrets are shown once, stored only as hashes, and omitted from audit metadata. Revocation retains safe audit history.

Supported application permissions

The transport/storage field remains abilities; its values are application Permissions values. The catalogue has 20 distinct permissions, with 27 supported type/permission combinations: four Administration, seven organisation and sixteen project selections. Shared names never expand a credential type's route boundary. The OpenAPI operation metadata specifies required and conditional permissions and whether the operation requires mutation-enabled execution. The existing confirmed web issuance request uses this shape (not a bearer API endpoint):

{
  "token_type": "project",
  "project_id": "<accessible project ULID>",
  "name": "Project reader",
  "abilities": ["view-projects", "view-controls"],
  "read_only": true,
  "expires_at": "<future ISO-8601 timestamp within the maximum lifetime>"
}

Organisation requests supply organisation_id instead of project_id. Administration requests supply neither target ID. Unsupported fields/bindings and unheld permissions are rejected; selecting a permission never changes the mode.

Administration

Issuance requires current manage-org-hierarchy. The issuer must additionally hold every selected permission and dependency. Administration supports:

Read and write provider operations share hierarchy authority; execution mode controls whether mutations are allowed. Publication and restricted read/upload remain separate explicit selections. Upload-only restricted creation returns a minimal receipt and does not grant content reads. Bulk operations check every resource. Provider UI and API actions share the existing hierarchy authority; user permissions and seeded roles were not changed for this alignment.

GET /organisations is paginated with 50 identities per page. POST /organisations requires mutation-enabled hierarchy authority, normal policy/licence/bootstrap checks and Idempotency-Key. It grants no role or permission. Matching creates replay for 24 hours; after expiry, discover before issuing another create. Continue setup using a separately issued organisation-bound credential, then operational work using a project-bound credential. Administration cannot use organisation/system/project editing or project operational route families.

Organisation

Issuance requires current access to the bound organisation and either manage-org-hierarchy or manage-projects. Eligibility grants no unselected permission. Organisation supports:

Minimal system discovery accepts selected/live hierarchy authority or view-projects plus manage-projects. Full system/context/logo operations still require hierarchy authority. Project identity/status can remain readable with view-projects; setup-only scope, readiness and provider fields are redacted unless manage-projects is also selected and held. Project configuration and population share management permission; initial population and failed-context retry retain normal readiness gates. Retry starts a new run under the requesting actor/credential, preserves existing records and requires current setup If-Match. Old jobs remain bound to their original credential. Organisation credentials cannot create organisations, administer providers, change access or read/edit project controls/assessments. Organisation register rows cannot select project controls/documents or system contacts.

Project

Issuance requires current access to the bound project and every selected permission and dependency. Project supports:

Register/evidence source references require selected and live source permissions: contacts use view-contacts, controls/library use view-controls, registers use view-registers and Docsuite uses view-docsuite. Unreadable source fields are redacted on reads and receipt replay; new unreadable references are rejected. Assessment properties are omitted without selected/live assessment-read authority. Task manager authority is not inherited just because the actor holds it: select manage-tasks. Existing assignment, workflow, licence, readiness, editability and archived-resource rules remain in force.

An approval-capable bearer can exercise its actor's approval authority without interactive confirmation for each decision. Editing does not imply approval, and approval does not imply editing. Select approval authority explicitly for the intended integration; normal workflow gates and decision-comment requirements apply.

Picker and credential handling

The token page filters supported permissions by type and live actor authority, selects shown dependencies, and keeps execution mode independent. Presets and select-all exclude approval and provider publication; select these explicitly. Presets are convenience selections, not role grants. Final document generation confirmation retains its normal workflow and grants no control approval authority.

The create-token form places type, name and searchable target selection first, then execution mode and expiry, followed by a searchable, scrollable permission table. Read/Write defaults off: credentials are read-only until the standard toggle is enabled. An explicit mode badge shows Read-only or Read/Write. The submit button names the chosen mode and uses an amber warning colour for Read/Write. The token list uses teal Read-only and amber Read/Write badges in the scope column. Permission filtering and Selected only affect visibility, not grants; required dependencies remain selected and locked. The checkbox is on the left; clicking a permission row toggles selection. Only friendly permission names are displayed. Switching token type clears the permission selection and filters. Permission presets never enable mutation execution automatically.

Create/revoke credentials through the authenticated web interface with its normal MFA/session/recent-confirmation gates. Store the one-time plaintext in an approved secret manager; never put it in URLs, code, logs, prompts, tickets or analytics. Use separate named credentials for targets/integrations and rotate before expiry. Revoke after exposure, departure or integration retirement. Disabled/deleted actors cannot use existing credentials. Routine password expiry or a forced-change flag alone does not revoke an otherwise valid bearer; explicitly revoke for incidents. Owners can revoke their individual credentials under Profile → API tokens. Administrators can selectively revoke another user's project, organisation or Administration token under Admin → Users → select user → API tokens → Revoke. This requires manage-users, plus manage-super-users when the owner is a Super User, and the normal credential-confirmation gate. If prompted to confirm access, return to the user page and select Revoke again. The confirmation names the token and owner. Only that credential is deleted; the account and other tokens stay available. The audit event records administrator, owner and token identifier without the secret or hash. Disabling an actor still blocks all their credentials when broader incident containment is needed.

API-started generation, population, provider imports, upload releases and context/ scope applicability work retain original actor/token attribution and revalidate before protected work and durable writes. Revocation, expiry, changed grants/mode, permission loss or access loss stops subsequent work; completed transactions are not rolled back. UI/system work retains its own authority path.

Creates retain bounded retry receipts; updates require current strong ETags under resource locks. Normal quarantine/scanning, parser/review and frozen-release gates remain. Linked URLs record references and are not fetched automatically.

Request budgets and security logging

Read and mutation limits apply per credential across all client IPs. Additional actor and organisation budgets aggregate credentials and actors respectively; Administration credentials use the actor budget because they have no bound organisation. Limits apply across operations within each read/mutation class. An independent per-IP ingress limit applies before authentication, including invalid credentials. All budgets use the configured shared cache in production. Respect Retry-After on 429 responses; changing IP or rotating credentials does not avoid aggregate budgets.

Defaults per minute: ingress 600/IP; reads 120/credential, 240/actor, 1200/organisation; mutations 30/credential, 60/actor, 300/organisation. Operators can configure API_INGRESS_RATE_LIMIT_PER_MINUTE, API_READ_RATE_LIMIT_PER_MINUTE, API_MUTATION_RATE_LIMIT_PER_MINUTE, API_ACTOR_READ_RATE_LIMIT_PER_MINUTE, API_ACTOR_MUTATION_RATE_LIMIT_PER_MINUTE, API_ORGANISATION_READ_RATE_LIMIT_PER_MINUTE and API_ORGANISATION_MUTATION_RATE_LIMIT_PER_MINUTE. Values must be positive. The shared-IP ingress budget may need tuning for integrations behind a common NAT.

Failed API requests include reads, deletions and authentication failures in safe application audit events. Correlation IDs are assigned before authentication. Events omit query values, request values and bearer credentials. Repeated 429 events are sampled once per IP per minute to avoid audit-write amplification; HTTP access logs retain individual response statuses.

Library Markdown attributes are limited to class and id. Arbitrary CSS and URL-bearing attributes are rejected; legacy attributes are stripped during rendering. PDF generation embeds only the document project's registered diagram and organisation logo as data and does not fetch arbitrary network or local-file assets.

Unsupported credentials

Credentials with retired, mixed, wildcard or unsupported grants, or a missing stored execution mode, are invalid. Revoke and reissue through the token page with a reviewed permission selection. Replacing a credential never transfers queued work to the new key. Environment upgrade and worker coordination belong in the repository's development smoke-testing guide.