# Auth.md — Agent Registration Metadata

> Machine-readable authentication and agent-registration guide for Pyramid Healthcare
> (https://www.pyramid-healthcare.com). Follows the workos/auth.md convention.

## Overview

This document tells autonomous agents and third-party clients how to register,
obtain credentials, and authenticate against Pyramid Healthcare's public APIs.
Discovery metadata is published at the standard well-known URIs; this file is a
human- and agent-readable summary that links them together.

- Resource server: `https://www.pyramid-healthcare.com`
- Authorization server (issuer): `https://itezwiuituuhkyspskmf.supabase.co/auth/v1`
- Protocol: OAuth 2.1 / OpenID Connect 1.0
- Bearer token transport: `Authorization: Bearer <access_token>` header

## Discovery Endpoints

| Purpose | URL |
| --- | --- |
| OpenID Connect discovery | `/.well-known/openid-configuration` |
| OAuth 2.0 authorization server metadata | `/.well-known/oauth-authorization-server` |
| OAuth 2.0 protected resource metadata | `/.well-known/oauth-protected-resource` |
| API catalog (RFC 9727) | `/.well-known/api-catalog` |
| Agent skills index | `/.well-known/agent-skills/index.json` |

## Agent Registration

Agents may register dynamically via [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)
Dynamic Client Registration.

- **register_uri**: `https://itezwiuituuhkyspskmf.supabase.co/auth/v1/oauth/register`
- **Method**: `POST`
- **Content-Type**: `application/json`
- **Required fields**: `client_name`, `redirect_uris`
- **Optional fields**: `grant_types`, `response_types`, `scope`, `token_endpoint_auth_method`,
  `contacts`, `logo_uri`, `policy_uri`, `tos_uri`

### Example registration request

```http
POST /auth/v1/oauth/register HTTP/1.1
Host: itezwiuituuhkyspskmf.supabase.co
Content-Type: application/json

{
  "client_name": "Example Agent",
  "redirect_uris": ["https://example.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "openid profile email",
  "token_endpoint_auth_method": "none"
}
```

The response returns a `client_id` (and `client_secret` for confidential clients)
that the agent uses in the authorization code flow.

## Supported Identity Types

- `human` — end-user of Pyramid Healthcare digital services (via authorization code + PKCE)
- `agent` — autonomous software agent acting on behalf of a human user (via authorization code + PKCE with `token_endpoint_auth_method: none`)
- `service` — confidential machine client (via `client_credentials` where explicitly provisioned)

## Supported Credential Types

- `oauth2_access_token` — short-lived bearer token (JWT), transported in `Authorization` header
- `oauth2_refresh_token` — long-lived rotation token exchanged at the token endpoint
- `oidc_id_token` — signed identity assertion (JWT) for `openid` scope
- `pkce_code_verifier` — required for public clients

## Supported Scopes

| Scope | Description |
| --- | --- |
| `openid` | OpenID Connect authentication |
| `profile` | Basic profile claims |
| `email` | Email address claim |
| `phone` | Phone number claim |

## Claims

Standard OIDC claims are returned from the UserInfo and ID token endpoints:
`sub`, `email`, `email_verified`, `name`, `phone_number`, `phone_number_verified`,
`iat`, `exp`, `iss`, `aud`.

- **claims_uri**: `https://itezwiuituuhkyspskmf.supabase.co/auth/v1/user`

## Revocation

Tokens may be revoked by the resource owner at any time.

- **revocation_uri**: `https://itezwiuituuhkyspskmf.supabase.co/auth/v1/logout`
- Method: `POST` with valid `Authorization: Bearer <access_token>`.

## Authorization Flow (summary)

1. Discover metadata via `/.well-known/oauth-authorization-server`.
2. (Optional) Register dynamically at `register_uri`.
3. Redirect the user to `authorization_endpoint` with PKCE `code_challenge`.
4. Exchange the returned `code` at `token_endpoint` for an access token.
5. Call Pyramid Healthcare APIs with `Authorization: Bearer <access_token>`.
6. Refresh with the `refresh_token` grant before expiry.
7. Revoke via `revocation_uri` on logout.

## Contact

- Security & agent-integration inquiries: `security@pyramidhealthcarepa.com`
- API documentation: `/docs/api.html`