# auth.md

Welcome, AI Agents! This document describes how you can register and authenticate with our API.

## Discovery
- OAuth Protected Resource Metadata: [`/.well-known/oauth-protected-resource`](https://samuiservices.com/.well-known/oauth-protected-resource)
- OAuth Authorization Server Metadata: [`/.well-known/oauth-authorization-server`](https://samuiservices.com/.well-known/oauth-authorization-server)

## Registration
We support multiple agentic registration methods described below:

### 1. Anonymous Registration Flow
To register anonymously and obtain an API key:
- **Registration URI:** `https://samuiservices.com/api/agent/register`
- **Method:** POST
- **Body:**
  ```json
  {
    "agent_name": "YourAgentName",
    "developer_email": "developer@example.com"
  }
  ```
- **Response:**
  ```json
  {
    "registered": true,
    "api_key": "samui_agent_key_xxxx",
    "agent_name": "YourAgentName"
  }
  ```
- **Verification / Claiming:** Use the claim_uri endpoint at `https://samuiservices.com/api/agent/claim` to link the agent profile.

### 2. Identity Assertion Flow (ID-JAG / Verified Email)
We support identity assertions using ID-JAG (Identity Assertion JWT) and verified emails. Provide the signed assertion during registration to get authenticated.

## Authentication
Our protected API resources require a Bearer token in the `Authorization` header:
`Authorization: Bearer <your_api_key>`