Getting started
Phasoric deliberately has more than one developer surface because the trust boundary for a one-time handoff is different from the trust boundary for an authenticated agent or a partner product.
1. Pick the contract
Use Handoff when the external product has produced a bounded work product and the next natural step is for the user to continue it in Phasoric.
Use MCP when an agent client needs bounded tools over a Phasoric Hosted mapping.
Use the Developer REST API when your backend or script needs direct hosted-vault reads, dry-run mutations, transactions, or provenance events.
Use Automation/OpenAPI for versioned events, approval-required action proposals, triggers, or webhook delivery workflows.
Use Product Runtime when you are building another product surface over Phasoric's stable application DTOs and authorization model.
2. Obtain the right credential
| Surface | Credential |
|---|---|
| Handoff | Phasoric-issued scoped Handoff client credential (bhc_…), kept server-side |
| Hosted MCP | Hosted access token (bda_…) from AI Connections & API settings; Premium and above |
| REST / Automation | The same hosted access-token format, independently authorized for Developer & Agent or Team |
| Product Runtime as a human developer | Entitled developer bearer token |
| Product Runtime as an installed product | Installation service-principal credential |
| First-party Phasoric product | First-party cookie/session where explicitly supported |
A vault mappingId, workspaceId, vaultId, Handoff token, or Product Experience ID is not a credential by itself.
3. Keep hosted and local boundaries explicit
Hosted APIs work with Phasoric Hosted state that the user has explicitly connected. They cannot read an arbitrary local browser vault.
When examples use BASALT_ORIGIN, set it to the supported Phasoric application/API origin for the environment you are using. The Developer Center hostname is documentation infrastructure; do not assume it is the API origin unless the deployed reference explicitly says so.
4. Make a read before a write
For REST/MCP, start by listing or reading the target hosted mapping. For Product Runtime, read context/capabilities before attempting a mutation. For Handoff, create a temporary handoff and redirect the user; do not import on link-open.
5. Preview mutations
Phasoric mutation surfaces are intentionally conservative:
- REST note writes and transactions default to dry run.
- MCP note mutations use the same hosted transaction boundary.
- Product Runtime hosted publishes use explicit preview/publish behavior and revision controls.
- Automation bridge actions are proposals until the applicable approval/execution boundary is satisfied.
6. Preserve idempotency and current revisions
Use stable idempotency keys for retryable write operations. When modifying or deleting an existing note, provide the current revision/hash required by that API. Phasoric should reject stale writes rather than silently overwriting newer knowledge.
7. Treat returned provenance as part of the contract
Do not strip source identifiers, revisions, actor information, or knowledge fingerprints if your workflow depends on auditability. Provenance is part of Phasoric's decision-intelligence model, not decorative metadata.