---
title: Authentication & environments
description: Understand Phasoric personal access tokens, Handoff clients, service principals, sessions, mappings, and origin boundaries.
slug: authentication
path: /authentication
section: Fundamentals
availability: supported
nav_order: 3
canonical_url: https://developers.phasoric.com/authentication
markdown_url: https://developers.phasoric.com/authentication.md
mirror_url: https://phasoric.com/developers/authentication
---
# 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:

```http
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:

```http
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:

```text
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:

```http
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.