# Formca auth.md - Agent Registration and Authentication

This document describes how autonomous AI agents, multi-agent orchestrators, and automated clients register, obtain credentials, and authenticate with the Formca platform.

## Agent Audience

This authentication specification applies to:
- Autonomous AI agents performing booking, schedule discovery, or service availability lookups on behalf of users.
- Business automation systems syncing appointments, calendars, and customer records.
- Model Context Protocol (MCP) clients connecting via Formca MCP server.

## Agent Registration & Provisioning

Formca supports programmatic agent registration per the Auth.md specification:

- **Registration Endpoint (`register_uri`):** `https://api.formca.io/v1/agents/register`
- **Claim Endpoint (`claim_uri`):** `https://api.formca.io/v1/agents/claim`
- **Revocation Endpoint (`revocation_uri`):** `https://api.formca.io/v1/agents/revoke`

### Supported Identity & Assertion Types

1. **ID-JAG (Identity Assertion):**
   - Type: `urn:ietf:params:oauth:token-type:id-jag`
   - Credential Types: `bearer_token`, `api_key`
2. **Verified Email:**
   - Type: `verified_email`
   - Credential Types: `bearer_token`, `api_key`
3. **Anonymous / Dynamic Provisioning:**
   - Type: `anonymous`
   - Credential Types: `bearer_token`

## Obtaining API Credentials Manually

1. Sign in to your business dashboard at [https://app.formca.io](https://app.formca.io).
2. Go to **Ayarlar > Geliştirici & API** (Settings > Developer & API).
3. Generate an API Key with the required scopes (`appointments:read`, `appointments:write`, `services:read`, `staff:read`).

## Request Authentication

All authenticated requests to the Formca API must supply the credential using the standard HTTP `Authorization` header:

```http
Authorization: Bearer <your_api_token_or_key>
```

## OAuth Metadata & Discovery Documents

- **Protected Resource Metadata (RFC 9728):** https://formca.io/.well-known/oauth-protected-resource
- **Authorization Server Metadata (RFC 8414):** https://formca.io/.well-known/oauth-authorization-server
- **OpenID Connect Configuration:** https://formca.io/.well-known/openid-configuration
- **API Catalog (RFC 9727):** https://formca.io/.well-known/api-catalog
- **AI Capability Catalog (ARD):** https://formca.io/.well-known/ai-catalog.json
- **MCP Server Card (SEP-1649):** https://formca.io/.well-known/mcp/server-card.json
- **LLM Guidance:** https://formca.io/llms.txt

## Scopes Supported

- `appointments:read`: View appointments, available slots, and customer bookings.
- `appointments:write`: Book, reschedule, or cancel customer appointments.
- `services:read`: Query business service offerings, durations, and pricing.
- `staff:read`: Query staff members, working hours, and resource calendars.