# TezApply auth.md

> Agent Registration & Authentication Specification for TezApply API and Services

## 1. Overview & Agent Audience

TezApply provides machine-readable agent authentication and registration protocols per the **Auth.md** standard. Autonomous AI agents, agentic software, and automated job outreach tools can discover authentication parameters, register agent credentials, and access authorized TezApply REST APIs.

Target Audience:
- Autonomous AI Agents and Multi-Agent Orchestrators
- Automated Job Search & Application Assistants
- Integration Bots and Workflow Automation Services

---

## 2. Authentication & Authorization Server Metadata

TezApply publishes standard OAuth 2.0 metadata for resource protection and agent registration:

- **OAuth Protected Resource Metadata (PRM)**: `/.well-known/oauth-protected-resource`
- **OAuth Authorization Server Metadata**: `/.well-known/oauth-authorization-server`
- **API Catalog**: `/.well-known/api-catalog`
- **LLM & Agent Documentation**: `/llms.txt`

---

## 3. Registration & Provisioning Endpoints

Agent registration and token issuance endpoints:

- **Agent Registration Endpoint**: `/api/v1/auth/register` (`POST`)
- **Token Exchange & Issuance Endpoint**: `/api/v1/auth/token` (`POST`)
- **Identity Claim Verification Endpoint**: `/api/v1/auth/claim` (`POST`)
- **Anonymous Token Provisioning**: `/api/v1/auth/anonymous-claim` (`POST`)
- **Credential Revocation Endpoint**: `/api/v1/auth/revoke` (`POST`)

---

## 4. Supported Authentication Methods

Agents can authenticate using any of the following methods:

1. **OAuth 2.0 Client Credentials Grant** (`client_credentials`)
   - For server-to-server agents with pre-registered `client_id` and `client_secret`.
2. **ID-JAG Assertion** (`urn:ietf:params:oauth:token-type:id-jag`)
   - Identity Assertion for Just-in-Time Agent Governance.
3. **Verified Email Assertion** (`verified_email`)
   - Verification of agent operator's confirmed email domain or identity.
4. **Anonymous Ephemeral Authentication** (`anonymous`)
   - Rate-limited ephemeral bearer tokens for anonymous browsing and job search discovery.

---

## 5. Credential Usage

All authenticated API requests must supply issued JWT bearer credentials in the HTTP `Authorization` header:

```http
Authorization: Bearer <your_agent_jwt_token>
```

Supported Scopes:
- `read`: Read public job listings, guides, and metadata.
- `write`: Create draft application content.
- `applications:write`: Submit and manage application tracking entries.
- `emails:send`: Request email outreach dispatch (requires user account authorization).

---

## 6. Flow & Event Metadata Summary

- **Identity Types Supported**: `["identity_assertion", "anonymous"]`
- **Assertion Types Supported**: `["urn:ietf:params:oauth:token-type:id-jag", "verified_email"]`
- **Credential Types**: `["bearer_token", "jwt", "ephemeral_jwt"]`
- **Revocation Event**: `token_revocation` supported at `/api/v1/auth/revoke`