Quickstart

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)

import { Client } from "@nebbos/sdk";
 
const client = new Client({ token: "nbbs_..." });
const tools = await client.mcp.listAvailableTools();
for (const t of tools) {
  console.log(t.name, "→", t.tierRequired);
}

curl -sS https://api.nebbos.ai/api/v1/mcp/list_available_tools \
  -H "Authorization: Bearer $NEBBOS_TOKEN" \
  | jq '.tools[] | {name, 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

The preceding call produces one entry in the hash-chained audit log. The entry is retrievable through audit_event_list, filtered by operator identity and time window. Each entry includes tool name, input hash, output hash, tier, and the chain hash. Chain entries constitute the audit-preparation evidence a compliance officer requires.

curl -sS "https://api.nebbos.ai/api/v1/audit/events?since=5m" \
  -H "Authorization: Bearer $NEBBOS_TOKEN" \
  | jq '.events[] | {tool, tier, outcome, input_hash}'