Concepts

Three mental models that explain the entire platform.

The 5-layer marketplace

ServiceDefinition (catalog) → ApiSpecTemplate (versioned) → ApiSpecBuild (frozen) → Tool (indexed) → App (your instance)

ServiceDefinition — A catalog entry. "Google Calendar" as a concept.
ApiSpecTemplate — A versioned OpenAPI specification owned by a Service.
ApiSpecBuild — A processed snapshot of a Template at a specific version. Tools live inside builds; agents resolve them at call time.
Tool — One operation (one OpenAPI path × method). Indexed for semantic search. Has a stable, bitemporal ID.
App — Your concrete instance: a Build + your credentials + end-user OAuth tokens.

The 3-layer identity

Critical for understanding auth and audit:

Name

Type

Required

Description

uid

Firebase Auth

required

Developer logged in the portal

aiClient.id

API key + Client ID

required

Machine agent making API calls

userId

string (unverified)

optional

End-user behind the agent — NOT authenticated

userId is for tracking only

Never use userId as an authorization signal. It comes from your application, unverified. We use it to scope OAuth tokens and audit trails. RBAC decisions are made on uid and aiClient.id only.

Organizations and tenancy

Every account belongs to an Organization.
Personal orgs are auto-created on signup.
Wallet, billing, audit logs, RBAC scopes — all scoped to the Organization.
Members carry roles: viewer < member < admin < owner.