# Auth.md

## Bulgarian Citizenship Inquiry Agent Registration & Authentication

Welcome to the automated agent registration and authentication specification for the Bulgarian Citizenship Status Inquiry API.

## Agent Audience

This authentication specification is intended for autonomous AI agents, Telegram bots, legal CRM integrators, and automated background monitoring systems querying Bulgarian Ministry of Justice citizenship records.

## Authorization & Discovery Metadata

- **OAuth Protected Resource Metadata (RFC 9728)**: [/.well-known/oauth-protected-resource](https://bgsorgulama.bulgaristanvatandas.com/.well-known/oauth-protected-resource)
- **OAuth Authorization Server**: [/.well-known/oauth-authorization-server](https://bgsorgulama.bulgaristanvatandas.com/.well-known/oauth-authorization-server)
- **OpenID Connect Discovery**: [/.well-known/openid-configuration](https://bgsorgulama.bulgaristanvatandas.com/.well-known/openid-configuration)
- **API Catalog (RFC 9727)**: [/.well-known/api-catalog](https://bgsorgulama.bulgaristanvatandas.com/.well-known/api-catalog)
- **Web Bot Auth JWKS Directory**: [/.well-known/http-message-signatures-directory](https://bgsorgulama.bulgaristanvatandas.com/.well-known/http-message-signatures-directory)

## Registration Endpoints

Agents can register and authenticate programmatically using standard endpoints:

- **Registration Endpoint**: `POST https://bgsorgulama.bulgaristanvatandas.com/agent/auth`
- **Claim Endpoint**: `POST https://bgsorgulama.bulgaristanvatandas.com/agent/claim`
- **Revocation Endpoint**: `POST https://bgsorgulama.bulgaristanvatandas.com/agent/revoke`

## Supported Identity & Credential Types

1. **Anonymous / API Key**:
   - Identity Type: `anonymous`
   - Credential Types: `["api_key"]`
   - Header: `Authorization: Bearer <API_KEY>`

2. **Identity Assertion (ID-JAG)**:
   - Identity Type: `identity_assertion`
   - Assertion Types: `["urn:ietf:params:oauth:token-type:id-jag", "verified_email"]`
   - Credential Types: `["jwt", "api_key"]`

3. **Scopes Supported**:
   - `read:status`: Query publicbg.mjs.bg application status and decree notes.
   - `query:file`: Submit case number and 6-digit PIN code for automated checks.

## Usage Example

```bash
curl -X GET "https://bgsorgulama.bulgaristanvatandas.com/api/status?reqNum=14820/2023&pin=582910" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <API_KEY>"
```