# Portravo auth.md

Portravo is a construction takeoff and estimating service. Agents act for a contractor who has a Portravo account; there is no way for an agent to create an account, and no anonymous or agent-identity credential. Two credentials exist.

## 1. OAuth for the MCP server (assistants)

- Protected resource: `https://portravo.com/mcp`
- Resource metadata (RFC 9728): [https://portravo.com/.well-known/oauth-protected-resource/mcp](https://portravo.com/.well-known/oauth-protected-resource/mcp)
- Authorization server issuer: `https://portravo.com/api/auth`
- Authorization server metadata (RFC 8414): [https://portravo.com/.well-known/oauth-authorization-server/api/auth](https://portravo.com/.well-known/oauth-authorization-server/api/auth)
- Client registration: dynamic client registration (RFC 7591) at [https://portravo.com/api/auth/oauth2/register](https://portravo.com/api/auth/oauth2/register). Public clients use `token_endpoint_auth_method: none`.
- Flow: authorization code with PKCE (S256 only) at [https://portravo.com/api/auth/oauth2/authorize](https://portravo.com/api/auth/oauth2/authorize), tokens from [https://portravo.com/api/auth/oauth2/token](https://portravo.com/api/auth/oauth2/token), refresh with the `offline_access` scope. Send `resource=https://portravo.com/mcp`; tokens are only valid for that resource.
- Scopes: `projects:read`, `projects:write`, `plans:write`, `extractions:write`, `estimates:read`, `offline_access`. Ask for the fewest the task needs.
- The person signs in to Portravo, finishes account setup if needed, and approves the requested scopes on a consent screen. Access tokens last 15 minutes; refresh tokens 30 days.
- Use: `Authorization: Bearer <access token>` on POST `https://portravo.com/mcp`. A missing, expired or revoked token gets a `WWW-Authenticate: Bearer resource_metadata="..."` challenge.
- Discovery: the AI Catalog at [https://portravo.com/.well-known/ai-catalog.json](https://portravo.com/.well-known/ai-catalog.json) lists the MCP Server Card at [https://portravo.com/mcp/server-card](https://portravo.com/mcp/server-card).
- Without a token, `tools/list`, `list_pricing_markets` and `preflight_takeoff` without `project_id` answer with markets, trades and published prices only; no account data.

## 2. API keys for the project REST API (integrations)

- The account owner creates a key in Portravo under Settings > Integrations ([https://portravo.com/settings](https://portravo.com/settings)), picking its scopes. Keys last 90 days and can be revoked there. An agent cannot create one.
- Use: `Authorization: Bearer <key>` on `https://portravo.com/api/v1`. An OAuth access token issued for the MCP server is accepted there too.
- Contract: [https://portravo.com/api/v1/openapi.json](https://portravo.com/api/v1/openapi.json). Guide: [https://portravo.com/developers/api](https://portravo.com/developers/api).

Keep credentials out of URLs, prompts, logs and screenshots. Questions: hello@portravo.com.