Authentication and scopes
These rules follow PL01-SCOPES. They describe the draft contract. A scope is a ceiling on access, not a permission grant.
Current authority wins
Section titled “Current authority wins”Every request must satisfy the intersection of current registration, active installation, token scopes, current user or service grant, company visibility, enabled modules, domain permissions and resource restrictions. Step-up and independent approval remain required where applicable. Checks happen before lookups, validation details, pagination and idempotent replay.
One token binds one tenant. A company path narrows access further. Tenant or company headers cannot override it; conflicting legacy headers are rejected. An account role in ACME-LK gives no authority in ACME-SG.
First-slice scopes
Section titled “First-slice scopes”| Scope | Permitted operation | Required current authority |
|---|---|---|
companies:read |
Read safe company metadata | org.company.view; currently visible installed companies |
ledger.accounts:read |
Read safe account definitions, without balances or payroll details | ledger.coa.view; Ledger enabled |
ledger.periods:read |
Read dates and open/closed status | Proposed ledger.coa.view; held until Ledger ratifies the mapping; Ledger enabled |
ledger.journal-drafts:write |
Create ordinary manual drafts as the user | ledger.journal.draft; FM/ACC FULL or CLK LIMITED to own drafts; Ledger enabled; never machines |
The read consent proposal covers OWN, ADM, FM, ACC, CLK, CSH, APR, AUD and VWR only within their current company permissions. AUD expiry limits consent/session eligibility. OWN, ADM, APR, AUD, VWR or CSH alone cannot consent to draft creation. Role unions remain company-specific; LIMITED never becomes unrestricted access.
Registration, installation and consent
Section titled “Registration, installation and consent”- A reviewed app owner registers metadata. Changes to redirects, grants or key ownership need step-up and review. Platform administration does not confer tenant-data authority.
- Tenant OWN/ADM installation administrators need current
access.user.manage, fresh passkey evidence, exact administrable companies and the mapped read permission. These are proposed new OAuth approval rules. - Service reads also need an independent OWN approver bound to client, company, scopes, expiry and purpose. The requester cannot approve the same grant. Proposed expiry is 90 days; owner transfer suspends it for review.
- A delegated draft installation ceiling needs the installation administrator and an independent company FM. The user still needs their own FM/ACC/CLK draft permission.
- Only the user gives their personal consent. Scope or company expansion requires fresh review/consent. No write scope is preselected.
A future consent screen must show the verified publisher and support contact, exact redirect domain, environment, named companies, scopes, expiry and revocation link. Enabling a company module follows the normal module rules; app consent does not introduce a separate activation checklist.
Token lifecycle and revocation
Section titled “Token lifecycle and revocation”Use Authorization Code + PKCE S256 for user apps, with state and OIDC nonce where appropriate. Use client credentials for approved service reads, preferably private_key_jwt. The proposed access token TTL is 300 seconds, with environment-specific issuer/audience and key trust. ID tokens are rejected by the API. No implicit or password grant is supported.
Proposed interactive refresh families rotate after every use, with 12-hour absolute and 30-minute inactivity limits; no offline access by default. Reuse revokes the family. Service clients have no refresh token.
Users can revoke their own consent/session; scoped tenant OWN/ADM can revoke installations; app owners can disable their client; platform/security can suspend a compromised client globally. Current authority must deny the next request across replicas. A five-minute token TTL is not a five-minute revocation delay. Authority outages fail closed. Already disclosed data cannot be recalled, and created drafts remain in audit history.
Outside this slice
Section titled “Outside this slice”Employee self, leave, claims, payslips, documents, POS, performance and organization-structure scopes are reserved future work. They cannot be selected here. No wildcard, admin, posting or general private-data OAuth scope exists in this contract.