Set up Keystone,
connect your data, and explain the numbers.
This first-pass docs hub is for operators, finance owners, and admins who need practical guidance: how to onboard an organization, connect providers, understand the dashboard, and review CFO-ready outputs.
Overview
Get oriented before your first sync
Keystone is organized around your active organization in Clerk. Start by confirming who owns setup, which providers you want to connect, and which teams need access to the dashboard.
Create or join the right organization
Every dashboard view, sync, and report is scoped to the active Clerk organization. Make sure you are operating in the intended tenant before you ingest anything.
Decide which provider path you need first
OpenAI, Anthropic, Google Cloud, AWS Bedrock, and CSV uploads all work as first-pass intake paths. Start with the source your finance or platform team can verify most easily.
Use an admin role for setup work
Provider connections, sync actions, and other write paths require organization admin permissions. Viewer-style access is intended for read-only consumption.
Setup
Prepare your workspace for reliable onboarding
The fastest clean setup is to start with one org, one provider, and one expected spend workflow so your first sync can be validated against known billing data.
Confirm your organization structure
Use a dedicated organization for the business unit or environment you want to measure. This keeps later reporting, alerts, and CFO outputs scoped correctly.
Choose one validation window
Pick a recent billing window or export you already trust. The first sync should be something your team can sanity-check without guesswork.
Keep setup credentials owner-controlled
Use provider credentials managed by your platform or finance owner rather than ad hoc personal keys so later sync ownership is clear.
How To
Connect providers and import usage data
Keystone validates provider credentials before saving them and stores sync status so operators can see whether a source is healthy, stale, or failing.
Start with the provider connection form
Provide the required credentials for OpenAI, Anthropic, Google Cloud, or AWS Bedrock. Keystone checks them before persisting the connection so invalid keys fail early.
Use CSV when you need a controlled import
CSV upload is the best fallback when you want a known static dataset, internal validation pass, or provider export that needs review before recurring syncs.
Review connection health after sync
The connections view surfaces latest sync result, last error, and recent activity so the ingest path is inspectable instead of a black box.
Guide
Read the dashboard the way finance and operators do
Keystone is built around the three-view model: what happened, what is happening next, and what is quietly leaking spend right now.
Use Windshield for forward-looking budget pressure
Windshield is the planning surface for upcoming spend, trend direction, and planned-versus-actual questions.
Use Rearview for historical accountability
Rearview is where you explain what actually happened across models, providers, and time windows after the usage data is normalized.
Use Blind Spots for anomaly and shadow-AI review
Blind Spots is for unexpected spikes, unmapped behavior, and spend patterns that need operator follow-up before the next billing surprise.
Reporting
Generate CFO-ready reporting with traceable context
The CFO brief flow is meant to be reviewable, not magical. Treat it as a reporting surface backed by current insights and source context.
Generate the brief after a trusted sync window
A CFO brief is only as good as the usage data behind it. Run it after you confirm the organization and ingestion window are the ones you actually want summarized.
Review the generated metadata
Use the page metadata and saved brief details to confirm when the report was produced and how it was generated before you circulate it.
Expand source data during review
The source payload exists so finance and operators can inspect the underlying context rather than trust a summary blindly.
Export the current brief as a PDF artifact
Use the PDF export once the narrative and metadata are correct. Keystone generates a real PDF so board-facing distribution does not depend on ad hoc browser printing.
Security
Understand how Keystone handles credentials and tenant data
The production posture assumes strict org isolation, encrypted provider credentials, and explicit failure handling instead of optimistic background magic.
Credentials are encrypted at rest
Provider secrets are encrypted server-side and only decrypted in memory during sync work. They should never be exposed in frontend flows or logs.
Organization claims drive data access
Keystone derives tenant scope from verified Clerk session claims. The system should not rely on a client-submitted org identifier for authority.
Readiness is observable
Deployments should expose a healthy `/health` response before you treat the environment as usable for customer data.
FAQ
Frequently asked questions
These are the questions operators and finance owners usually ask during first setup and early reporting reviews.
Do I need to finish provider setup before inviting teammates?
No. You can invite teammates first, but only organization admins can complete provider connection and sync actions. Read-only collaborators can review dashboards afterward.
What should I do if a provider sync fails?
Start with the Connections page. Keystone records recent sync status and the latest error so you can distinguish bad credentials from a transient provider or configuration issue.
When should I use CSV instead of a live provider connection?
Use CSV when you need a controlled historical import, when the source data must be reviewed before ingestion, or when a team is onboarding with exported billing data first.
Can one organization see another organization's data?
No. The system is designed around organization-scoped access using Clerk claims and row-level security expectations in the backend data model.
How should I validate a CFO brief before sharing it?
Check the active organization, confirm the latest sync window, review the brief metadata, and expand the source data so the narrative matches the underlying usage context.
Next step
Ready to connect your first organization?
Start with one trusted provider or CSV window, validate the first sync, then use Keystone's dashboard and CFO brief flows as the operating layer for the rest of the rollout.