# auth.md

> Agent Authentication & Registration Specification for Kolyn.io (https://kolyn.io)

---

## Agent Audience

- **Audience**: `https://kolyn.io`
- **Target**: Autonomous AI agents, conversational assistants, and automation clients (A2A, MCP).
- **Resource Server**: `https://kolyn.io`
- **Issuer**: `https://kolyn.io`

---

## Agent Auth Discovery Metadata

```json
{
  "agent_auth": {
    "skill": "https://kolyn.io/auth.md",
    "register_uri": "https://kolyn.io/api/contact",
    "claim_uri": "https://kolyn.io/api/contact",
    "identity_types_supported": ["anonymous"],
    "assertion_types_supported": ["verified_email"],
    "credential_types_supported": ["none"],
    "verified_email": {
      "assertion_types_supported": ["verified_email"],
      "credential_types_supported": ["none"],
      "claim_uri": "https://kolyn.io/api/contact"
    },
    "anonymous": {
      "identity_types_supported": ["anonymous"],
      "credential_types_supported": ["none"],
      "claim_uri": "https://kolyn.io/api/contact"
    }
  }
}
```

```yaml
agent_auth:
  skill: https://kolyn.io/auth.md
  register_uri: https://kolyn.io/api/contact
  claim_uri: https://kolyn.io/api/contact
  identity_types_supported:
    - anonymous
  assertion_types_supported:
    - verified_email
  credential_types_supported:
    - none
  verified_email:
    assertion_types_supported:
      - verified_email
    credential_types_supported:
      - none
    claim_uri: https://kolyn.io/api/contact
  anonymous:
    identity_types_supported:
      - anonymous
    credential_types_supported:
      - none
    claim_uri: https://kolyn.io/api/contact
```

---

## Standalone Registration & Provisioning Flow

### 1. Provisioning Endpoints
- **Register Endpoint (`register_uri`)**: `https://kolyn.io/api/contact`
- **Claim Endpoint (`claim_uri`)**: `https://kolyn.io/api/contact`
- **Public docs**: `https://kolyn.io/llms-full.txt`

Kolyn.io does not issue OAuth access tokens. Public reads are anonymous. A human quote is `POST /api/contact`.

### 2. Supported Registration Methods

#### A. Verified Email Registration Method
- **Method Name**: `verified_email`
- **Assertion Types Supported**: `["verified_email"]`
- **Credential Types Supported**: `["none"]`
- **Claim URI**: `https://kolyn.io/api/contact`
- **Description**: The agent posts name, email and message. Kolyn replies by WhatsApp or email. No Bearer token is minted.

```http
POST https://kolyn.io/api/contact
Content-Type: application/json

{
  "name": "Ana",
  "email": "ana@example.com",
  "message": "Quiero AEO para mi sitio",
  "service": "aeo"
}
```

#### B. Anonymous Access Method
- **Method Name**: `anonymous`
- **Identity Types Supported**: `["anonymous"]`
- **Credential Types Supported**: `["none"]`
- **Claim URI**: `https://kolyn.io/api/contact`
- **Description**: Public access to services, docs and contact channels without credentials.

```http
GET https://kolyn.io/llms-full.txt
GET https://kolyn.io/api
GET https://kolyn.io/api/contact
```

---

## Credential Use & Authorization

Public GETs do not require `Authorization`. `POST https://kolyn.io/api/auth/token` returns `unsupported_grant_type`.

### Supported Scopes
- `services:read`: Public service catalog and docs.
- `contact:write`: Start a consultation via `/api/contact`.

---

## Discovery Endpoints Reference

- **Protected Resource Metadata (PRM)**: `https://kolyn.io/.well-known/oauth-protected-resource`
- **Authorization Server Metadata**: `https://kolyn.io/.well-known/oauth-authorization-server`
- **OpenID Configuration**: `https://kolyn.io/.well-known/openid-configuration`
- **JWKS URI**: `https://kolyn.io/.well-known/jwks.json`
- **Service Documentation**: `https://kolyn.io/llms-full.txt`