# 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. | Credential | Maximum lifetime | Boundary | | --- | --- | --- | | Project, read-only | 90 days | One explicit existing project | | Project, mutation-enabled | 30 days | Same project | | Organisation, either mode | 30 days | One explicit existing organisation | | Administration, either mode | 30 days | Supported installation operations and explicitly accessible organisation identities | 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): ```json { "token_type": "project", "project_id": "", "name": "Project reader", "abilities": ["view-projects", "view-controls"], "read_only": true, "expires_at": "" } ``` 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: | Permission | Operations / dependency | | --- | --- | | `manage-org-hierarchy` | Accessible organisation discovery/identity and organisation creation; installation-owned provider identities, options, artefacts and imports | | `publish-provider-assurance-packages` | Assertion review, release configuration/publication and provider deletion containing releases; requires `manage-org-hierarchy` | | `view-restricted-provider-artefacts` | Conditional restricted projection, download, import, review or deletion; requires `manage-org-hierarchy` | | `upload-restricted-provider-artefacts` | Conditional restricted upload/link creation; requires `manage-org-hierarchy` | 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: | Permission | Operations / dependency | | --- | --- | | `manage-org-hierarchy` | Organisation/system full identity, canonical context and logo reads; identity/context/logo mutations and system creation | | `view-projects` | Accessible project discovery, safe identity, engagement and population status | | `manage-projects` | Project setup creation/editing, full scope/context/provider selections, setup options, artefacts and population; requires `view-projects` | | `view-contacts` | Same-system active contact discovery | | `manage-contacts` | Same-system contact creation/PATCH; requires `view-contacts` | | `view-registers` | Organisation/system-owned manual definitions and rows | | `manage-registers` | Canonical organisation/system manual-row creation/PATCH; requires `view-registers` | 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: | Permission | Operations / dependency | | --- | --- | | `view-projects` | Project discovery, safe inputs and engagement | | `manage-projects` | Read full canonical context/scope; requires `view-projects`; does not enable organisation-key setup writes | | `view-controls` | Non-assessment controls/evidence and library working-copy reads | | `view-control-assessment` | Assessment fields/actions; requires `view-controls` | | `edit-control-implementation` | Implementation editing/transitions, evidence creation/linking/metadata/replacement/removal/cancellation and library mutations; requires `view-controls` | | `edit-control-assessment` | Assessment editing/transitions; requires `view-controls` and `view-control-assessment` | | `approve-edits` | Implementation approval/rejection; requires `view-controls` | | `approve-assessments` | Assessment approval/rejection; requires `view-controls` and `view-control-assessment` | | `view-contacts` | Same-system active contacts; no contact authoring | | `view-registers` | Project manual rows, same-system shared rows and project-context manual register review history | | `manage-registers` | Editable project-owned manual rows and project-context review recording; requires `view-registers` | | `view-docsuite` | Catalogue, dependencies, status and authorised draft/final downloads | | `generate-docsuite` | Normal generation workflow; requires `view-docsuite` | | `view-tasks` | Task visibility and permitted assignment/team actions; actions also require mutation-enabled mode | | `manage-tasks` | Manager visibility and claim/release overrides; requires `view-tasks` | | `view-restricted-provider-artefacts` | Conditional restricted provider material in control operations; requires `view-controls` | 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.