# hcalls Authentication & Agent Auth Specification

> OAuth 2.0 Authorization Code with PKCE, Client Credentials, and WorkOS `auth.md` Agent Authentication.

## Machine-Readable Auth Metadata
- **RFC 9728 Protected Resource Metadata**: `https://hcalls.com/.well-known/oauth-protected-resource`
- **RFC 8414 Authorization Server Metadata**: `https://hcalls.com/.well-known/oauth-authorization-server`
- **OpenID Discovery**: `https://hcalls.com/.well-known/openid-configuration`

## Public Client for Developers & Autonomous Agents
- **Client ID**: `hcalls-public`
- **Client Secret**: None (Public client with PKCE S256 code verification)
- **Token Endpoint**: `https://hcalls.com/oauth/token` (`/api/auth/oauth/token`)
- **Authorization Endpoint**: `https://hcalls.com/oauth/authorize`
- **Registration Endpoint**: `https://hcalls.com/oauth/register`

## WorkOS Agent Auth Discovery Block
```json
{
  "agent_auth": {
    "register_uri": "https://hcalls.com/oauth/register",
    "skill": "https://hcalls.com/auth.md",
    "identity_types_supported": ["anonymous", "identity_assertion"],
    "anonymous": {
      "credential_types_supported": ["client_secret_basic", "client_secret_post", "none"]
    },
    "identity_assertion": {
      "assertion_types_supported": ["urn:ietf:params:oauth:token-type:id-jag", "verified_email"],
      "credential_types_supported": ["jwt-bearer"]
    }
  }
}
```

## Free Self-Serve API Access
1. Create a free account at https://hcalls.com/login (50 credits awarded instantly, no credit card required).
2. Authorize via `/oauth/authorize?client_id=hcalls-public&response_type=code&scope=sessions:create+sessions:read+resumes:read&redirect_uri=http://localhost:3000/callback&code_challenge=...`.
3. Exchange code for JWT access token at `/oauth/token`.
4. Include token in subsequent requests: `Authorization: Bearer <access_token>`.