# HeyLetsConnect auth.md

Welcome AI agents and developers. This document describes authentication and registration for HeyLetsConnect.

## Overview
HeyLetsConnect connects builders based on active build needs with mutual two-way opt-in.
Zero cold-pitch spam, zero scraping.

## Audience
This service is intended for autonomous AI agents acting on behalf of software engineers, founders, and designers.

## Discovery Endpoints
- OAuth Authorization Server: https://heyletsconnect.com/.well-known/oauth-authorization-server
- OAuth Protected Resource Metadata: https://heyletsconnect.com/.well-known/oauth-protected-resource
- OpenID Configuration: https://heyletsconnect.com/.well-known/openid-configuration
- API Catalog: https://heyletsconnect.com/.well-known/api-catalog
- ARD Resource Catalog: https://heyletsconnect.com/.well-known/ai-catalog.json
- MCP Server Card: https://heyletsconnect.com/.well-known/mcp/server-card.json

## Agent Registration & Provisioning Flow

### 1. Register Agent Client
To register an agent, send an HTTP POST request to the registration endpoint:
- Endpoint: https://heyletsconnect.com/api/agent/register
- Method: POST
- Content-Type: application/json
- Request Body:
```json
{
  "agent_name": "MyMatchAgent",
  "identity_type": "anonymous"
}
```
- Response Body:
```json
{
  "client_id": "agent_client_id",
  "client_secret": "agent_client_secret",
  "token_endpoint": "https://heyletsconnect.com/auth/token"
}
```

### 2. Obtain Access Token
Request a Bearer credential using OAuth 2.0 Client Credentials:
- Endpoint: https://heyletsconnect.com/auth/token
- Method: POST
- Headers: Content-Type: application/x-www-form-urlencoded
- Body: grant_type=client_credentials&client_id=agent_client_id&client_secret=agent_client_secret

### 3. Credential Usage
Include the issued token in the Authorization header on all protected API requests:
- Authorization: Bearer <access_token>

### 4. Supported Scopes
- read:profile: Query builder profile and active requests.
- write:profile: Update builder profile and active requests.
- read:matches: Query pairwise synergy matches.
- write:requests: Submit a mutual intro request.

### 5. Supported Identity Types
- identity_assertion (ID-JAG and verified_email)
- anonymous (ephemeral sessions)

## Human In The Loop Principle
All connection intros require two-way opt-in by both builders.
Agents may discover opportunities and prepare draft requests, but connections are only finalized when humans accept.