Build with Phasoric

Public contracts for handoffs, hosted APIs, MCP, automation, partner products, and governed extensions.

supported
View Markdown

Authentication & environments

Phasoric separates who is calling, what product is calling, and which workspace/vault the caller may access. Do not collapse those identities into one token or route parameter.

OAuth-connected MCP applications

Remote interactive MCP clients should use Phasoric's OAuth authorization-code flow. The authorization grant is bound to one user, one registered/CIMD client, exact redirect URI, granted MCP scopes, PKCE S256 challenge, and the canonical https://phasoric.com/api/mcp resource. OAuth MCP access tokens are not personal access tokens and cannot be used with Developer REST or unrelated account APIs.

Phasoric stores authorization codes, access tokens, and refresh tokens only as SHA-256 hashes. Codes expire after five minutes, access tokens after one hour, and rotating refresh tokens after 30 days. Reusing a rotated refresh token revokes the affected grant and family.

Personal access tokens

Hosted MCP and the Developer REST API use separate, server-authoritative plan entitlements. Premium and Professional include bounded MCP access without Developer REST API access; Developer & Agent and Team include both capabilities.

  1. In Phasoric, open Settings → AI Connections & API.
  2. Create a personal access token.
  3. Store it as a secret; do not place it in client-side JavaScript, public repositories, redirect URLs, or analytics.
  4. Send it as:
Authorization: Bearer bda_…

PATs are account-bound and plan-bound. Rotate a token if it may have been exposed.

Handoff client credentials

Handoff creation uses a separate scoped client identity:

Authorization: Bearer bhc_…

Keep Handoff client credentials in your backend. The continueUrl returned by Phasoric contains an opaque one-time token and must not contain the client credential or Handoff payload.

Product Runtime service principals

A product installation should not use an employee's personal token as its long-lived identity. Approved product integrations use an installation service principal scoped through:

organization
→ product definition
→ customer installation
→ service principal
→ credential scopes
→ organization workspace assignment
→ installation logical-vault grant

Revoking any required link must remove future access without deleting the user's knowledge.

First-party browser sessions

First-party Phasoric product surfaces may use authenticated Phasoric sessions where the runtime explicitly supports them. Independent origins should use an explicit bearer credential. Do not copy Phasoric cookies into another product.

Identifiers are not authority

These values identify targets but do not grant access:

  • mappingId
  • workspaceId
  • logical vaultId
  • scopeId
  • Product Experience ID
  • product hostname
  • organization ID

The server must resolve current account, workspace, organization, installation, and vault authority for the authenticated principal.

Mapping IDs

Developer REST and most MCP vault tools require an explicit Phasoric Hosted mappingId. You may provide it where supported in the request body/query or through:

X-Phasoric-Mapping: <mapping-uuid>

A mapping is an explicit hosted-vault target, not a default “current vault.”

Origins and CORS

Browser-origin trust and data authorization are separate checks. A verified first-party/custom Product Experience origin can be trusted for the browser request boundary without gaining data access. Workspace membership, product installation grants, and logical-vault grants remain authoritative.

Environment guidance

Use different credentials for development and production. Never reuse production bearer credentials in local examples, recorded demos, CI logs, or documentation screenshots.

Handoff references require HTTPS except where the contract explicitly permits localhost HTTP for development.

OAuth discovery and issuer URLs use OAUTH_ISSUER, which must be the same trusted HTTPS application origin as APP_URL in production. Phasoric production uses both values as https://phasoric.com; request Host headers are never used to construct OAuth identifiers.