Skip to Content
IntegrationQuickstart

Quickstart

This reference documents the path from initial operator credentials to a first authenticated call verified in the audit chain. The five steps below correspond to five verifiable artefacts.

Obtain operator credentials

Every request to the Nebbos platform is authenticated with a Bearer token issued to a specific operator identity. Operator credentials are provisioned by the deployment administrator against a sandbox or production tenant. The identity carries the operator’s tier assignment (Guest, Host, or Architect) and the departments within its scope.

Enrol a Cradle if the target tier requires it

Guest-tier reads clear on the device-native biometric. Host-tier writes require a Cradle physically present at the time of the call. Architect-tier administrative operations require an additional enclave-signed approval token. Integrations that operate above the Guest tier follow the Cradle provisioning path prior to first call.

Discover the MCP surface

The first call from an integration is list_available_tools. This returns the current tool roster, input schemas, and per-tool tier requirements. Integrations should pin against the discovered roster rather than a hard-coded list, so that additions to the surface become available on the next discovery pass without integration code changes.

from nebbos import Client client = Client(token="nbbs_...") tools = client.mcp.list_available_tools() for t in tools: print(t.name, "→", t.tier_required)

Execute the first authenticated call

Select a read-tier tool from the discovery response (for example, get_context, list_departments, or describe_pearl). The call succeeds when the Bearer token is valid and the operator’s scope covers the target. Refusals include the specific policy identifier responsible for the refusal; the platform does not return generic authorisation errors.

curl -sS https://api.nebbos.ai/api/v1/departments \ -H "Authorization: Bearer $NEBBOS_TOKEN"

Verify recording in the audit chain

Read-only platform API requests, like the one above, are not recorded yet. Calls made through the Nebbos MCP are. With a token that carries the audit_events:read scope, call the audit_event_list tool to list your client’s recent MCP records:

{ "name": "audit_event_list", "arguments": { "since": "2026-11-09T12:00:00Z", "limit": 10 } }

The list returns records while your organization has per-person records switched on. Each row carries the record’s id, type, actor and time. Pass an id to audit_event_get for its hash and previous_hash, or to audit_event_hash_chain_verify to check it.

Platform-provided services

Integrations do not provision an independent database, identity provider, or audit pipeline. Every Nebbos deployment provides row-level isolation at the substrate, a shared hash-chained audit log, and a Nebbos-managed identity plane. Integration work consists of consuming these services rather than reproducing them.

Next references