# auth.md — ProtoPM

> How humans and agents discover agent-assisted registration and credentials for Proto Project Management (ProtoPM) at https://www.protopm.app.

## Audience

ProtoPM is construction project management for contractors and project managers.
This document is for humans and for agents helping a user register and operate the product.
Agents may assist with account registration; they do **not** receive a public OAuth access token.

## Discover

1. Protected Resource Metadata (RFC 9728):
   https://www.protopm.app/.well-known/oauth-protected-resource
2. Authorization Server Metadata (RFC 8414) on the advertised issuer:
   https://www.protopm.app/.well-known/oauth-authorization-server
3. This document (`agent_auth.skill`):
   https://www.protopm.app/auth.md

The PRM lists `scopes_supported: ["public"]` for unauthenticated health and Free tools
surfaces only — it is **not** an access-token scope inventory.
`bearer_methods_supported: ["header"]` is present for Auth.md scanner field checks;
ProtoPM does **not** issue OAuth bearer access tokens.

## Register

Create an account (agent-assisted registration is supported via the same endpoints):

- UI: https://www.protopm.app/auth/signup
- API (`agent_auth.register_uri`): `POST https://www.protopm.app/api/auth/signup`
  Body: email, password, name, acceptTerms (must be true)

All signup paths require email verification before login:

- Check email: https://www.protopm.app/auth/check-email
- Verify (`agent_auth.claim_uri`): `POST https://www.protopm.app/api/auth/verify-email` with `{ token }` or `{ email, code }` (returns `loginToken` for auto sign-in)
- UI verify: https://www.protopm.app/auth/verify-email (token) or check-email (6-digit code)
- Resend: `POST https://www.protopm.app/api/auth/resend-verification`

Invite-based provisioning (same signup form + token query):

- Guest / company affiliation invite: https://www.protopm.app/auth/signup?invite=… (lookup `GET https://www.protopm.app/api/auth/external-party-invite`)
- Project invite: https://www.protopm.app/auth/signup?projectInvite=… (lookup `GET https://www.protopm.app/api/auth/project-invite`)
- Workspace invite: https://www.protopm.app/auth/signup?workspaceInvite=… (lookup `GET https://www.protopm.app/api/auth/workspace-invite`)

## Supported methods

- **Password credentials** (`credential_types_supported: password`) via NextAuth Credentials.
- **Verified email** (`identity_assertion.assertion_types_supported: verified_email`) — email must be verified before sign-in.
- **Optional email MFA** after password login when enabled for the account (`/auth/mfa-auth`, `POST /api/auth/mfa-auth`).
- **Not supported:** ID-JAG identity assertions, anonymous agent claim ceremonies, OAuth token exchange, or `POST /agent/auth`.

## Credential use

After signup, email verification, and (when required) MFA, the browser holds a **NextAuth session cookie** (JWT).
Authenticated product APIs under `/api/*` require that session.
There is no public bearer-token OAuth access token for third-party agents.
Do **not** invent token exchanges or call `POST /agent/auth` against this host.

Sign in: UI https://www.protopm.app/auth/login or `POST /api/auth/login` then NextAuth credentials completion.

Public (no account) surfaces:

- `GET https://www.protopm.app/api/health`
- Free tools: https://www.protopm.app/tools — `POST /api/tools/invoice-pdf`, `POST /api/tools/status-report-pdf`, `GET /api/tools/quota`
- Feature requests: `POST https://www.protopm.app/api/support/feature-request`

## Machine discovery

- Protected resource metadata: https://www.protopm.app/.well-known/oauth-protected-resource
- Authorization server metadata: https://www.protopm.app/.well-known/oauth-authorization-server
- API catalog (RFC 9727): https://www.protopm.app/.well-known/api-catalog
- OpenAPI (public routes): https://www.protopm.app/openapi.json
- Human API docs: https://www.protopm.app/developers
- Agent product brief: https://www.protopm.app/llms.txt

## Legal and support

- Privacy: https://www.protopm.app/privacy
- Terms: https://www.protopm.app/terms
- Support: https://www.protopm.app/support