Rylvo API Reference

Every turn captures

• Active prompt IDs + resolved placeholders
• Guardrails evaluated (and which triggered)
• Connectors invoked + request/response bodies
• Evolution rules injected into the system prompt
• Active flow step + transitions evaluated (if a flow is attached)
• Token usage + cost (runs on your own BYOK key)

Good for

• Reproducing a failure from a trace replay
• Iterating on a prompt before promoting to active
• Verifying a new guardrail actually fires
• Comparing two bots side-by-side (/dashboard/bots/[botId]/compare)

Your LLM key (BYOK)

Every AI feature — free

Bot chat, Workspace Architect, Agent Evolution, Self-Improving Prompts, Edge Case Engine, Red Team, broadcasts, embeddings — all run on your own provider key with zero markup. No Credits, no wallet, no monthly grant.

Prepaid wallet (optional)

Conversation-storage overage

A prepaid USD wallet covers only conversation-storage overage beyond your plan's included pool and wallet-funded retention add-ons. Dodo charges plan subscriptions separately. Top up from $5 at Dashboard → Billing. AI features never draw from it.

Plan gates

• requireFeature — feature locked or downgraded
• requireQuota — usage ≥ plan cap
• requireProviderKey — AI feature needs your own LLM key (BYOK, free)
• requireStorageEventsBudget — storage pool exhausted
• Returns PlanAccessError with upgradeTarget

Durable outbox architecture

• API routes publish to a durable billingOutbox before Pub/Sub
• Cloud Function billingOutboxWorker is the only account writer
• Atomic transactions with idempotency + negative clamp
• Daily billingReconciliation runs ledger integrity checks
• Port-based design: all billing code depends on abstract interfaces

Write paths

• Engine: make_observability_ingest_hook (live channels)
• Playground / Architect: adapters → POST /v1/observability/ingest
• Rich operator context on metadata.turn_context
• Hierarchical observations: spans, generations, tools, guardrails, retriever, agent

Read paths

• Dashboard traces: canonical-backed projectors
• Analytics: analytics-rows Postgres aggregates
• Billing: sum_cost_by_bot (per-bot cap)
• Audience / GDPR: canonical customer rows

Analytics Rooms

Customizable dashboards with a widget grid. Create, save, and share rooms.

• Default room auto-seeded on first visit
• Bot/org-scoped date range per room
• Viewer+ read, operator+ create/edit
• Share via deep link

Widgets

Build from a catalog or pick from templates. Each widget has its own date range, bot scope, and visualization.

• Request volume, token breakdown, latency
• Model usage, cost, verification health
• Escalation rate, recent traces, cost by bot/model/conversation
• Template gallery for common dashboards

Data sources

Aggregates from the canonical trace store and the billing ledger.

• Canonical traces via analytics-rows
• Internal (dashboard / MCP): GET /v1/analytics/companies/{id}/overview
• Internal (dashboard / MCP): GET /v1/analytics/companies/{id}/runs
• Transactions feed for cost widgets

Date ranges

Preset or custom windows.

• 1h, 24h, 7d, 30d, 90d, all time
• Custom start/end day boundaries
• Per-widget range overrides

Room document

• name (1-200 chars), createdBy (UID)
• filters: botId (string | "all"), env (all|test|production), dateRange (1h|24h|7d|30d|90d|all)
• charts: array of AnalyticsRoomChartConfig
• Real-time Firestore listener for room list updates

Chart card config

• type: 17 legacy types + custom_widget
• position (0-indexed), title? override
• width: half | full  |  height: compact | normal | tall
• color: 8 colors (blue, emerald, amber, red, purple, pink, cyan, neutral)

Custom widget engine (Langfuse-style)

• 4 views: traces, tool_calls, cost, runs
• 19 metrics: count, unique_users, total_cost, p95_cost, total_tokens, avg_latency, pass_rate, error_rate, etc.
• 11 breakdowns: none, bot, model, env, status, user, channel, source, day, hour, week
• 7 chart types: line, bar_v, bar_h, big_number, pie, histogram, pivot
• Filters: 9 columns, 7 operators (=, !=, in, not_in, contains, starts_with, >, <)
• topN: limit for breakdown charts (default 10)

Default room seed (7 widgets)

• Total Traces (big_number, blue) + Total Cost (big_number, emerald)
• P95 Latency (big_number, amber) + Error Rate (big_number, red)
• Traces Over Time (line, blue, breakdown: day)
• Cost by Model (bar_h, emerald, breakdown: model, topN: 8)
• Verification Distribution (pie, emerald, breakdown: status)

Dashboard templates (4 categories)

• cost — spend tracking, token economics, billing (9 widgets)
• performance — latency, throughput, bot + tool perf
• usage — volume, users, channels, conversations
• quality — verification pass/fail, errors, guardrails

Widget rendering pipeline

• 1. Load data (traces, runs, transactions, bots)
• 2. resolveWidget() converts legacy types to WidgetConfig
• 3. applyRoomScope() injects room's botId filter
• 4. WidgetRenderer dispatches to chart component
• 5. computeWidget() / computeHistogram() aggregates
• Legacy types with no equivalent render "retired" card

RBAC & plan limits

• Read: any org member (viewer+) — rooms are org-wide
• Create/Update/Delete: admin+ only
• Feature: advancedAnalytics — Lite+ required
• Free: feature upgrade prompt; analytics rooms need Lite+
• No per-room count quota — unlimited within plan tier

Dashboard UI features

• Room sidebar (real-time, rename/delete menu, + New Room)
• Drag-and-drop chart reordering (position updated on drop)
• Room customizer modal (name, filters, chart management)
• Widget builder + templates + saved widget library
• Date range override (per-user, localStorage)
• Responsive: 2 columns desktop, 1 column mobile

Graph layout

• Bots on the left → Prompts in the center → Agent groups on the right
• Edges show bot prompt assignments via prompt.botId
• Org-level prompts (botId = null) connect to an org virtual node
• Parent → child inheritance drawn within the prompt column
• Group-shared prompts connect to their agent group

Interactions

• Click a prompt → open prompt detail
• Click a bot → open bot page
• Hover any node → tooltip with full name and metadata
• Scroll/pinch to zoom, drag to pan
• Zoom/fit buttons for quick navigation

Manual edit by a teammate from the dashboard

Applied via Workspace Architect (conversational setup / edit mode)

Produced by the Self-Improving optimizer or Agent Evolution rule generator

Accepted from an Edge Case Engine fix proposal

Internal migration or default seed

Created in response to a red-team finding

Flow document (FlowDoc)

• name, description
• mode: guided | strict
• start_step_id: entry step (must be defined)
• steps: FlowStep[]
• enabled: boolean

Step structure (FlowStep)

• id (unique), name
• goal: injected into the system prompt for this step
• collect: data fields to slot-fill before advancing
• allowed_tools: string[] | "all" | "none"
• allowed_agent_id: sub-agent for this step (groups)
• terminal: ends the flow

Transition

• to: target step id
• kind: always | data_complete | intent | condition | tool_result
• intent (kind=intent), expr (kind=condition)
• tool (kind=tool_result): fires when it ran successfully this turn

Runtime state (FlowState)

• flow_id, current_step_id
• visited: step ids seen this session
• done: flow reached a terminal step
• One FlowState per session, advanced each turn

Graph validation

• At least one step; step ids unique
• start_step_id must be a defined step
• Every transition target must exist
• intent / condition / tool_result carry their field
• All steps reachable from start (BFS)

Bot & group attachment

• Bot: bots/{botId}.flowId
• Group: agentGroups/{groupId}.flowId
• Attach via /attach so the field is not dropped by the model write-path
• Engine reads flowId off the raw doc per turn

Runtime execution (per turn)

• 1. Read flowId + load the flow (flow_loader.load_flow)
• 2. Resolve the session's FlowState (start on first turn)
• 3. Inject the step goal; scope allowed_tools; list collect
• 4. advance() evaluates transitions and moves to the next step
• 5. A terminal step marks the flow done

Versioning

• Each update snapshots the prior revision
• GET .../versions lists prior revisions
• Restore = load a revision into the editor and Save
• Best-effort — a snapshot failure never blocks the save

Plan gating (flows feature)

• flows is a Pro+ feature gate (require_feature)
• Not a per-count quota — no max_flows limit
• Free / Lite: not available
• Pro / Team / Enterprise: available

RBAC

• Read: any org member
• Create / Update / Delete / Attach: requires the flows feature
• All endpoints run authorize_org (org membership)
• Written only via engineFetch — never Firestore directly

Trace datasets

Pin canonical traces into a shared collection for debugging, regression testing, or qualitative review.

• Pin from the Traces page or browse unpinned traces inside the dataset
• Trace source: canonical, legacy, or dashboard
• Inline trace replay + detail drawer
• Shared comment thread with the Traces page
• Soft-archive or hard-delete a dataset

People datasets

Group end-user profiles for segmentation, cohort review, or export.

• Collect end-user profiles from Audience
• Read-only detail view per profile
• Reuse for broadcast audience targeting

Client registry document

• clientId: "client_" + 12 random base64url chars
• clientName (1-200), redirectUris[]
• grantTypes: authorization_code, refresh_token
• tokenEndpointAuthMethod: none | client_secret_post
• clientSecretHash: SHA-256 hash (null for public clients)
• Global collection (not org-scoped); plaintext secret never persisted

Client types & secret management

• Public (PKCE-only): no secret issued, authMethod="none"
• Confidential: 32-byte random base64url secret, authMethod="client_secret_post"
• Secret returned ONCE at DCR response; only SHA-256 hash stored
• Constant-time comparison (timingSafeEqual) prevents timing attacks

Grant types & token flow

• Authorization Code (PKCE required): authorize → consent → token exchange
• Refresh Token Rotation: atomic Firestore transaction (revoke old, issue new)
• Org ID embedded in self-describing token: rfr_{base64url(orgId)}~{random}
• CSRF protection: HMAC-SHA256 on consent form

Token lifetimes

• Access token: 24 hours (RS256 JWT, aud-bound to https://rylvo.com/mcp)
• Refresh token: 30 days sliding window (rotated on each use)
• Refresh token family ceiling: 365 days absolute
• Authorization code: 10 minutes

Scopes (3)

• rylvo:read — view bots, analytics, conversations, KB
• rylvo:write — create/update bots, prompts, knowledge, settings
• rylvo:admin — manage org settings, members, integrations
• Default: "rylvo:read rylvo:write"

Security features

• RS256 JWT signing with key versioning (OAUTH_JWT_PRIVATE_KEY_PEM in prod)
• PKCE S256 required (plain rejected in production)
• Audience binding (RFC 8707) prevents confused-deputy attacks
• CSP: nonce-locked, HSTS, X-Frame-Options DENY
• Revoked JTI tracking: Firestore + in-memory LRU (max 10k)

Caching strategy

• Client metadata: 5 min TTL, max 5,000 entries
• JWT validation: negative (5s spam) + positive (2s revocation-aware), max 10k each
• Firebase session: 30s TTL, max 2,000 entries
• JTI revocation: in-memory LRU, max 10,000 entries

RBAC & plan limits

• oauthClients.view — viewer+ (all members)
• oauthClients.revoke — admin+ (admin or owner)
• OAuth collections are server-only (Admin SDK writes)
• NOT plan-gated — available to all plans (free → enterprise)
• Composite index required on oauthRefreshTokens.clientId

13 channel types

• widget — Website chat (origins, accent color, greeting, position, branding)
• whatsapp — Meta Cloud API (phoneNumberId, verifyToken)
• slack — (teamId, botUserId, signingSecret, channels[])
• telegram — (botId, webhookSecret, allowedChatIds, collectFeedback)
• discord — (applicationId, publicKey, guildId, commandName)
• msteams — (appId, appPasswordPrefix, tenantId)
• messenger — (pageId, verifyToken, appSecretPrefix)
• instagram — (igUserId, verifyToken, appSecretPrefix)
• sms_twilio — (accountSid, fromNumber, messagingServiceSid?)
• whatsapp_twilio — (same as SMS, connector adds whatsapp: prefix)
• line — (channelId, channelSecret, channelAccessToken, botUserId)
• email_inbound — (inboxAddress, fromAddress, replyMode, Resend)
• custom — (inboundSecret, label?)

Setup status state machine

• needs_setup → verified, deprecated (incomplete; cannot enable)
• verified → live, deprecated (test passed; can enable)
• live → verified, deprecated (enabled and receiving)
• deprecated → verified, needs_setup (restorable)
• enabled only allowed when setupStatus in [verified, live]
• First successful test auto-promotes to live (if no sibling enabled)

One-enabled-per-type rule

• Enforced at API layer via Firestore transactions (runTransaction)
• On create/patch with enabled=true: query for existing enabled config with same botId + channelType
• Returns 409 Conflict if duplicate found
• Firestore rules enforce immutability of botId and channelType

Health monitoring

• Status: ok | error | idle
• 3+ consecutive errors flips status to "error"
• Notification fanout on first error and at 3-in-a-row; 15-min cooldown
• Append-only event log (last 10 events, ring buffer) eliminates RMW hotspot
• Tracks inboundCount, outboundCount, errorCount, consecutiveErrors

Secret storage & redaction

• Full tokens in env vars (e.g. TELEGRAM_BOT_TOKEN_{prefix})
• Encrypted tokens in Firestore as AES-256-GCM v1: blobs
• Token prefixes (first 8 chars) stored in plaintext for display
• GET responses strip encrypted fields before sending to client
• Resolution order: env var → encrypted Firestore → legacy plaintext

Webhook idempotency

• 24-hour fingerprint cache at /dedup/{fingerprint}
• Format: {channel}:{platform_id} (e.g. telegram:12345)
• Platform retries are safe — duplicates silently ack'd
• TTL: 24 hours (Firestore TTL policy)

Inbound webhook flow (14 steps)

• 1-4: Buffer body, parse, early ack, pre-config signature check
• 5-8: Kill switch, channel lookup, org suspension, per-org rate limit (60 cap / 120/min)
• 9-12: Post-config ack, parse to NormalizedInbound, session resolution, dedup check
• 13-14: Record inbound, execute bot turn + send reply (3-retry) + record outbound/error
• All synchronous within webhook request (15s timeout)
• Discord special case: returns type:5 (thinking) immediately, runs in background

RBAC & plan limits

• channels.view — viewer+ (read)
• channels.manage — admin+ (create/update/delete)
• channels.test — operator+ (test connection)
• channels.rotate_secret — admin+ (rotate secrets)
• No per-plan channel limits — unlimited per plan
• Health subcollection is read-only for clients (server-only writes)

Supported clients

• Claude Code — remote HTTP install command + /mcp authorization
• Cursor — mcp.json remote server configuration
• Windsurf — mcp_config.json remote server configuration
• Zed — context_servers settings entry
• Codex CLI — codex mcp add + codex mcp login
• Other Streamable HTTP clients — verify OAuth support with the client

Security model

• OAuth 2.1 with PKCE (S256) — browser flow on first install
• RS256 JWT access tokens, 24-hour TTL
• Refresh tokens rotate on every exchange
• Every call is org-scoped: token org_id must match the resource
• A leaked token can act only in its bound org until expiry or revocation

1. Intent

Capture goal, industry, tone, compliance constraints

2. Research

Pull org profile defaults, relevant industry templates, prior sessions

3. Blueprint

Propose bots + workflow + guardrails + KB + connectors

4. Review

User approves / edits the blueprint in natural language

5. Generate

Write prompts, guardrails, connectors, rules, KB stubs

6. Verify

Auto-run bot tests on the new bot(s) and score readiness

7. Apply

Commit as versioned resources, tagged source=architect

8. Handoff

Summarise what was built, link to Mission Control & Playground

Connections

Add one or more storage targets. Each target receives a copy of every conversation event.

• PostgreSQL, Supabase, Neon, PlanetScale
• MySQL, Turso, MongoDB, Redis
• Webhook (none / API key / Bearer / HMAC auth)
• Credentials encrypted at rest

Schema Designer

Map Rylvo's conversation fields to your own table columns or JSON keys.

• Custom field mapping per target
• Preview the output schema and test DDL before going live
• Drivers only INSERT — you run the DDL on your side

Sync Logs + Dead Letter

Per-event push history with status, latency, and error details.

• Success / failure / retry status per target
• Webhook retry with exponential backoff (0.5 s → 1 s → 2 s)
• Inspect the exact payload that was sent
• Dead Letter Queue for terminal failures
• Live / Test toggle isolates playground traffic

Retention

How long Rylvo keeps its own operational copy of your conversations.

People

Paginated, server-driven list of end-users with 50-row default and 200-row maximum cursor pages.

• Filter by channel, consent scope, forgotten status, or free-text search
• Bot-scoped filtering with data-collection field predicates
• Full person page with Overview, Sessions, Profiles, Activity, and Audit tabs
• Bulk tags, consent, sessions, removal, export, merge, and eligible broadcast actions
• Anonymous widget captures and test identities stay separate from production People
• Keyboard shortcuts: / search, j/k navigate, Enter inspect

Audience Rooms

Saved filter presets that act like persistent views. Create rooms for common cohorts and share them with your team.

• Save any filter combination as a named room
• Dirty indicator when current filters diverge
• Pins & Discussion panel per room
• Deep-linkable via ?room= URL param

Segments

Reusable filters that resolve into concrete member lists for broadcasts and exports.

• Basic predicates: all users, active within N days, by channel, min conversations
• Profile predicates: checkpoint achieved, field value, completeness threshold
• Live preview with match count before saving
• One-click link to bot broadcast tab

Insights

Cached aggregate analytics computed from a snapshot (6h TTL). Org-wide or bot-scoped.

• Onboarding funnel, channel mix, consent breakdown
• Engagement depth, activity recency, hour-of-day heatmap
• Field-fill rates, top tags, completeness histogram
• Bot leaderboard (org-wide only)

Imports & Exports

Bring legacy CRM contacts in and export segments for your data warehouse.

• CSV import wizard: upload → map columns → preview → commit (idempotent)
• Segment export to CSV (up to 5,000 rows)
• 15 MB file limit plus a plan-specific row limit

Consent & Privacy

Govern how end-user data is collected and retained.

• Consent scope tiles: none, short_term_only, personalize, full
• GDPR forgotten-users queue with deep-links
• Retention policy: effective days, shorten override, extend add-ons
• The scheduled retention sweep purges expired records

Dataset document

• name (1-200 chars), description (max 2000)
• kind: "people" (discriminator; legacy docs without kind = "trace")
• peopleCount: denormalized end-user count
• retentionPolicy: { mode: "inherit" } (not enforced for people)
• archived: soft-delete flag

Item document

• externalId (1-500 chars, end-user identifier)
• source: "audience_room" | "people_page"
• addedBy, addedByName, addedAt
• snapshot: channel, displayName, consentScope, turnCount, lastSeenAtMs, firstSeenAtMs
• Doc ID = externalId → add/remove is idempotent

Kind discriminator: people vs trace

• people: groups EndUserDoc profiles, no retention enforcement, no export lock
• trace: groups TraceView traces, active retention, export lock
• Both in same Firestore collection (datasets)
• Filtering: .filter(r => r.data.kind === "people")

3 creation flows

• From Audience Room pins: createPeopleDatasetFromRoomPins() — fetches all pins, source="audience_room"
• From People Datasets page: create empty dataset, add people individually
• From People page: addPeopleToDataset() bulk add, source="people_page"

Quota enforcement (maxDatasets)

• Free: 1 | Lite: 10 | Pro: 50 | Team: 50 | Enterprise: unlimited (-1)
• Transactional count check (race-safe inside Firestore transaction)
• Archived datasets excluded from count; only kind="people" counted
• Error: PlanAccessError code="quota_exceeded", status 429

RBAC

• Read: any org member (viewer+)
• Create: operator+ (must set createdBy = auth.uid, name required)
• Update: operator+  |  Archive: operator+
• Delete: admin+ (hard delete + all items in chunks of 500)
• Items: read = member; create = operator+; delete = operator+

Idempotent operations

• Add item: returns { added: false } if already exists
• Remove item: returns { removed: false } if doesn't exist
• peopleCount incremented/decremented atomically
• Cannot add people to archived dataset

Relationships & audit

• Audience Rooms: pins → dataset items via createPeopleDatasetFromRoomPins()
• Broadcasts: NOT currently used as broadcast targets (future: "dataset" target type)
• Audit: people_dataset.created / updated / archived / deleted / item_added / item_removed
• Resource type: "people_dataset"

5-step composer

Audience → Channels → Content → Schedule → Review. Platform rules are surfaced at audience-pick time, never at delivery time.

• 4 audience sources: saved segment, upload, paste, all past chatters
• Toggleable channels with per-channel rule annotation
• Template + LLM-enrichment + per-row variables
• One-time, recurring (hourly → monthly), or "Send now"

12 broadcast channels

Email, in-app, WhatsApp, SMS (Twilio), WhatsApp (Twilio), Telegram, LINE, Slack, Discord, MS Teams, Messenger, Instagram, Web Widget. Each annotated with cold-send verdict and platform cap.

• WhatsApp: approved-template picker synced from Meta Graph
• WhatsApp (Twilio): rides Twilio Programmable Messaging with whatsapp: E.164 prefix
• SMS: opt-in gated, Twilio REST direct from the dispatch route
• LINE: reply/push via LINE Messaging API; channel secret + access token encrypted at rest
• Telegram / Web Widget / Discord: cold-send blocked with explainer

Audience uploads

Server-parsed CSV / XLSX (SheetJS) and paste-list with classifier and dedupe. Up to 50k rows per upload; per-row variable columns merge into the template at send time.

• Auto-detect identifier kind: phone, email, channel id
• Warnings surfaced before commit
• Optional "save to audience" mirror into endUsers

Delivery tracking

Every recipient writes a botBroadcastDeliveries row: queued / sent / failed / skipped, plus provider message ids where available.

• Per-run doc with per-channel sent / failed / skipped counts
• History drawer groups deliveries by channel + status
• Audit log: broadcast.created / scheduled / deleted

Rate caps & safety

Token-bucket rate limiter per channel in the cron runner. Caps mirror documented platform ceilings so a hot run can't suspend the underlying account.

• WhatsApp: 4,800/min (~80/s/number, Meta default)
• SMS: 60/min (Twilio conservative)
• Operators can lower per-broadcast, never raise above platform cap

Capabilities & RBAC

Four capability keys gate the feature, mirroring the rest of the dashboard.

• broadcasts.view — viewer+
• broadcasts.create — operator+
• broadcasts.send — admin+
• broadcasts.delete — admin+

Role hierarchy (ranked)

Four roles with strict rank-based enforcement. No action can target a member at or above your own rank.

• Owner (rank 3) — full access, billing, transfer ownership, manage SSO
• Admin (rank 2) — manage bots, keys, team, approvals, view audit log
• Operator (rank 1) — run bots, tests, interventions, approve requests
• Viewer (rank 0) — read-only dashboard access

Capability matrix (selected)

• team.view — viewer+
• team.invite — admin+
• team.remove_member — admin+
• team.change_role — admin+
• team.transfer_ownership — owner
• audit.view — admin+
• audit.export — admin+ (+ Pro plan)
• org.manage_sso — owner (+ Enterprise)

Invitations (email-based)

Admin+ invites by email. Plan limit enforced at invite and acceptance time. Deterministic invite ID from SHA256 hash. Rate limit: 10 invites/min.

• Default expiry: 7 days. Status: pending / accepted / expired / cancelled
• Atomic write: invitation + audit log + org usage counter in one transaction
• Acceptance: email must match, plan limit re-checked, member doc created
• Resend / cancel are admin+ actions, both audit-logged

Join requests (cross-org)

Non-members can request to join with a profile (role, workType, interests, useCase). Admins approve or deny with optional reason.

• Profile captures: founder / engineer / PM / designer / ops / analyst / other
• Work type: building agents, integrating API, managing workflows, analyzing data, exploring
• Audit actions: page_access.approved / page_access.denied

Page access grants

Granular elevation for two gated pages: audit_log and billing. Non-admins see a "Request Access" button.

• Request fans out in-app notification to all admins
• Approve → pageId added to member's pageAccessGrants array
• Deny → optional resolverNote. Revoke removes the grant
• Access: role grants capability OR explicit pageAccessGrant

Role change & removal

Cannot change own role, cannot act on same/higher rank, cannot assign above own rank. Removal is soft-delete only.

• Demotion enqueues durable outbox event for side-effects (API key revocation)
• Removal: status → "deactivated", revokes all API keys via outbox
• Ownership transfer: atomic swap, two audit entries, org.ownerId updated
• SSO/SAML: Enterprise plan only, owner-only capability

Two-stage write pattern

Every mutation stages an audit event into the outbox in the same Firestore transaction — atomicity is guaranteed. A Cloud Function drains the outbox into the canonical, read-only audit log.

• Stage 1: auditOutbox (transactional, same batch as mutation)
• Stage 2: auditLog (durable, read-only, drained by worker)
• HMAC-SHA256 integrity signature on every outbox doc
• Both web (Admin SDK) and Python API write through the same pipeline

Action catalog (200+)

Covers every material action: team, API keys, org, bots, workflows, prompts, tests, edge cases, guardrails, KB, traces, mission control, evolution, automation, MCP Hub, skills, audience, broadcasts, connectors, auth, and setup sessions.

• 40+ resource types (member, bot, prompt, guardrail, trace, broadcast…)
• Each entry: actor, action, resourceType, resourceId, details, IP, UA, source
• Source discriminator: web / api / mcp / system

Filtering & search

Filter by action, resourceType, resourceId, source, date range, actor email, and actor name. Full-text search across all fields including details JSON.

• Cursor-based pagination (opaque cursor: timestamp + docId)
• Default 25/page, max 500/request
• Rate limit: 120 req/min per IP on the BFF endpoint

Export & compliance

CSV export with all fields. Gated by capability and plan.

• Columns: id, timestamp, actorName, actorEmail, actorId, action, resourceType, resourceId, details
• Requires audit.export (admin+) AND Pro+ plan
• Audit logs are immutable once canonicalized
• Retention follows org-specific policy; GDPR purge via observability endpoints

RBAC

View and export are separately gated. Non-admins can request access via the page-access grant system.

• audit.view — admin+ OR pageAccessGrants: ["audit_log"]
• audit.export — admin+ AND Pro+ plan
• Non-admins see "Request Access" on the audit-log page

Integrity & security

HMAC-SHA256 signature on every outbox doc prevents tampering. Firestore rules block direct writes to auditLog.

• Signed fields: idempotencyKey, action, resourceType, resourceId, actor, details, source
• Canonical JSON with sorted keys
• No direct client writes to auditLog — all go through outbox staging
• Reader handles both nested actor objects and flat legacy fields

API key document

• name — human-readable label
• keyPrefix — first 12 chars for display
• keyHash — SHA-256 of raw key (never store raw)
• environment — production | staging | development
• permissions — API scopes array
• rateLimitOverride — calls/min (null = default 60)
• botId — optional bot binding

Key generation & hashing

• Format: rylv_{40 hex chars} (46 chars)
• Entropy: 20 bytes = 160 bits (crypto.getRandomValues)
• Hashing: SHA-256 via Web Crypto API
• Only hash persisted; raw key shown once at creation
• Prefix (first 12 chars) stored for display identification

Permission scopes (4 + 2 wildcards)

• respond — POST /api/v1/bot-run + widget-poll
• kb:read — POST /api/v1/kb/query
• kb:write — POST /api/v1/kb/documents
• trace.read — reserved for future
• * — full access  |  kb:* — all KB
• Normalization drops unrecognized scopes; defaults to ["respond"]

Authentication flow

• Headers: Authorization: Bearer | X-API-Key | X-Rylvo-Key
• SHA-256 hash raw key, collection-group query by keyHash
• Verify status == "active", extract orgId from path
• Async update lastUsedAt (non-fatal if fails)
• Returns AuthIdentity with permissions + rateLimitOverride

CRUD operations

• create: generate + hash + normalize, batch write (doc + counter + audit)
• list: filter by status, ordered by createdAt desc
• update: name, environment, permissions, botId + audit
• revoke: status → "revoked", decrement counter + audit
• revokeAllForMember: bulk revoke on member removal
• hardDelete: physical deletion (provisioning rollback)

Rate limiting

• Default: 60 calls/minute per key
• Override via rateLimitOverride field
• Token bucket via consumeTokenUnified()
• 429 response with Retry-After header
• Per-route buckets (bot-run, kb/query, etc.)

RBAC & plan limits

• apiKeys.view — admin+
• apiKeys.create — admin+
• apiKeys.revoke — admin+
• Free: 1 | Lite: 10 | Pro: 25 | Team: 25 | Enterprise: unlimited
• Quota enforced in Firestore rules (withinApiKeyQuota)
• Non-admins see RestrictedPlaceholder

Audit & cleanup

• Events: api_key.created / updated / revoked (with actor, IP, UA)
• Bulk revoke logs { count, memberUid }
• Bot deletion: hard-deletes bound keys, decrements active count only
• Workspace Architect: auto-creates key with default permissions, rollback via hardDelete
• Migration route: normalizeApiKeyPermissions backfill (idempotent)

Connector tool approval

• Triggered when tool has safety_restrictions.requires_approval = True
• approval_id format: aprv_{tool_call_id}
• Default TTL: 24 hours (86400s)
• Fire-and-forget: tool returns failure with approval_id immediately
• Bot/frontend polls status separately; no auto re-invoke on approval

MCP tool approval

• Permission levels: allow | require_approval | deny
• Risk-based defaults: low/medium → allow, high/critical → require_approval
• Default TTL: 10 minutes (600,000 ms)
• argsPreview (redacted JSON, max ~2KB) + optional llmRationale
• Real-time Firestore subscriptions for pending approvals

State machine

• pending → approved (via service.approve)
• pending → denied (via service.deny with reason)
• pending → expired (auto-expiry when TTL elapses)
• Only pending → approved/denied allowed (idempotent)
• Double-approve/deny returns None (already resolved)
• Mission Control adds: auto_denied status

Mission Control urgency levels

• immediate — 15s timeout, low-risk informational
• standard — 120s timeout, data access / PII-related
• extended — 900s timeout, financial / legal / compliance
• Expiry computed server-side (createdAt + timeoutSeconds)
• Includes riskScoreAtTime + riskSignals[] + conversationContext

ApprovalService methods

• request_approval() — create pending, persist, log event
• approve() — verify pending, update, log, idempotent
• deny() — verify pending, update + reason, log, idempotent
• list_pending() — query + filter expired + log stale

Expiration & cloud functions

• cleanupExpiredMcpApprovals — every 5 min, MCP approvals past TTL
• missionControlExpireApprovals — every 2 min, MC approvals past timeout
• Both write audit entries for system-initiated expiry
• Frontend polling: 1-30s exponential backoff, 5-min local timeout

RBAC

• Connector approvals: read = admin+; write = server-only (rules: false)
• MC approvals: read = member; create/update = operator+; delete = admin+
• MCP approvals: read = member; create/update = operator+; delete = admin+
• resolve_approval capability: operator+ (Mission Control)
• MCP Hub Approvals page: admin+ for approve/deny buttons

Audit & analytics

• MC expiry writes audit: eventType "approval_resolved", actor "system_sweep"
• Analytics: MCApprovalResolvedEvent { request_id, bot_id, action_type, resolution, response_time_ms, urgency }
• Audit log: approval.requested / approved / denied / expired / resolved
• Idempotency key on MC approvals for exactly-once semantics

In-app notification document

• userId (recipient), orgId, type
• title, message, link?
• data?: Firestore primitives (string | number | boolean)
• read: boolean, readAt: Timestamp | null

Trace comment mention document

• recipientUid, type (trace_mention | comment_reply | room_mention | pin_mention)
• payload: commentId, entityType, entityId, entityLabel, actorUid, actorName, snippet (~120 chars)
• Optional: parentRoomId, traceId, traceSource, traceLabel

60+ types across 8 categories

• team (8): join_request, member_joined, page_access_*
• mission_control (7): alert_rule, guardrail_escalation, channel_error, byok_unhealthy, wallet_low
• retention (2): retention_warning, retention_deleted
• edge_cases (2): edge_case_alert, guardrail_triggered
• billing (10+): low_balance, credits_low, quota_exceeded, subscription_*
• broadcasts (1), system (2): broadcast, welcome

Delivery channels (4)

• In-app: real-time Firestore subscriptions (<100ms)
• Email: Resend (mention emails, welcome; per-member opt-in)
• Webhooks: Slack, Discord, Teams, generic (2 retries, 500ms backoff, 8s timeout)
• Bot tools: send_notification__{slug}__{id} runtime tools (best-effort)

Real-time unified inbox

• useNotificationInbox(): merges mentions + in-app, scoped to the active org
• Parallel per-org Firestore subscriptions; other workspaces surface as unread counts + switch affordance
• Exposes: items[], unreadCount, otherOrgUnread[], loading, markItemRead, markAllRead, deleteItems
• Max 100 per org per subscription

Lifecycle & triggers

• Created (read=false) → Mark Read → Delete (hard-delete)
• Mark all read: capped at 200 docs per call
• Triggers: guardrail escalations, degraded attachments, observability alerts, join requests, broadcasts, mentions, welcome
• Engine triggers are fire-and-forget post-hooks (never block bot response)

Notification channels (Mission Control)

• Types: slack, email, webhook, discord, teams
• config: webhookUrl?, emails?, headers?
• events[]: which alert events trigger this channel
• botIds?: optional bot linking
• lastUsedAt, lastStatus (success | failed)

RBAC & preferences

• In-app: read = userId == auth.uid; update = only read/readAt fields; delete = false (via API)
• Mentions: read = orgMember + recipientUid match; create = actorUid == auth.uid
• Channels: read = member; create/update/delete = admin+
• Dispatch API: operator+ required
• Preferences: notificationPrefs.mentionEmail (default true)