# a3rbly Agent Authentication Specification (auth.md)

This document provides machine-readable and human-readable authentication instructions for automated agents, web crawlers, and client applications communicating with a3rbly.com.

```yaml agent_auth
version: "1.0"
resource: "https://a3rbly.com"
discovery_document: "https://a3rbly.com/.well-known/oauth-protected-resource"
authorization_server: "https://a3rbly.com/.well-known/oauth-authorization-server"
identity_types:
  - type: "anonymous_guest"
    description: "Open keyless access for casual queries, automated web crawlers, and evaluation agents."
    request_shape:
      method: "POST"
      endpoint: "https://hzproejhrfszrluuizax.supabase.co/functions/v1/parse-i3rab"
      headers:
        Content-Type: "application/json"
      body:
        sentence: "<arabic_sentence>"
        action: "parse"
        isGuest: true
  - type: "api_key"
    description: "Authenticated self-serve key for developers and high-volume autonomous agents."
    request_shape:
      headers:
        apikey: "<YOUR_API_KEY>"
        Authorization: "Bearer <YOUR_API_KEY>"
scopes:
  parse:read:
    description: "Execute Arabic dependency parsing, sentence analysis, and I'rab."
  grammar:read:
    description: "Look up definitions, inflection tables, and grammatical rules."
  tashkeel:write:
    description: "Generate diacritical vowel marks on Arabic text."
idempotency:
  supported_header: "Idempotency-Key"
  format: "UUID v4"
```

## Self-Serve Developer Access
1. Sign up instantly at [https://a3rbly.com/signup](https://a3rbly.com/signup)
2. Manage your API keys and quotas at [https://a3rbly.com/developers](https://a3rbly.com/developers)
3. Full API Reference: [https://a3rbly.com/api](https://a3rbly.com/api)