Skip to Content
IntegrationAuthentication & tiers

Authentication & tiers

The Nebbos platform uses a three-tier authentication model. Each tier corresponds to a defined authentication artefact and a defined operation scope. Every request carries an identity and a tier assignment; write operations additionally carry a delegation token verified by the substrate.

Tier definitions

TierInternal designationAuthentication requirementAuthorised operationsArtefact
GuestL1 · StarterDevice-native biometricReads across the operator’s scope; low-risk tool callsBearer token issued following a WebAuthn assertion on the operator’s device
HostL2 · TeamBiometric plus Cradle physically presentWrite operations within the operator’s organisationBearer token plus Cradle-signed delegation. The Cradle countersigns each request; requests without a valid countersignature are refused.
ArchitectL3 · EnterpriseBiometric, Cradle, and enclave-signed approval tokenSubstrate mutation, organisation creation and dissolution, cross-organisation operations, doctrine-cluster ratificationBearer, Cradle delegation, and enclave attestation. Approvals are signed per action inside the enclave.

Tier assignment

Tier assignment is a property of the operator identity provided to the integration by the platform. Integrations do not select a tier. A Guest-tier identity cannot execute a Host-tier operation; the substrate refuses the operation regardless of application-layer intent. Operators elevate to higher tiers through the device-side authentication flow (biometric, then Cradle, then enclave for Architect).

Testing across tiers requires separate sandbox identities, one per tier, provisioned by the deployment administrator. Attempts to escalate a single identity through application-layer code are refused at the substrate. Refusals are recorded in the audit chain.

Token lifetimes

  • Bearer tokens expire fifteen minutes after issuance.
  • Cradle-signed delegations remain valid while the Cradle is physically connected. Removal of the Cradle invalidates in-flight delegations.
  • Enclave approvals are single-action; no long-lived enclave token exists.

Bearer tokens should be refreshed before expiry. If a call returns HTTP 401, refresh the token and retry once. The substrate returns explicit error codes for authentication failures; integrations should propagate these failures rather than absorbing them silently.

Audit-chain recording of authentication

Every tool call made with a token is recorded in the hash-chained audit log with the acting identity, its delegator and the session’s attestation level. The platform records the attestation level but does not yet require it; biometric, Cradle and enclave factors are not enforced yet.

See The audit chain for the record fields and how records are checked.