# CodeJa Agent Authentication Guide (auth.md)

> Specification for AI agents to authenticate and interact with CodeJa APIs.

## 1. Discover
CodeJa supports RFC 9728 Protected Resource Metadata and RFC 8414 Authorization Server Metadata.
- **Protected Resource Metadata**: `https://codeja.dev/.well-known/oauth-protected-resource`
- **Authorization Server Metadata**: `https://codeja.dev/.well-known/oauth-authorization-server`

## 2. Pick a Method
Agents can access CodeJa resources using:
1. **Anonymous Mode**: Access public endpoints (`/llms.txt`, `/pricing.md`, `/.well-known/api-catalog`, `/api/ask`).
2. **Bearer Token Authentication**: Perform actions requiring user identity or elevated privileges using standard OAuth 2.0 Bearer tokens in the `Authorization` header.

## 3. Register (`register_uri`)
Agents can register client metadata or user credentials via:
- Endpoint: `POST https://codeja.dev/api/auth/register`

## 4. Claim (`claim_uri`)
Agents claiming an existing user session or token assertion can supply an identity assertion or ID token:
- Endpoint: `POST https://codeja.dev/api/auth/token`

## 5. Use the Credential
Include the token in all HTTP API requests:
```http
Authorization: Bearer <your_access_token>
```

## 6. Errors
Unauthenticated calls to protected API routes return an HTTP 401 response with standard `WWW-Authenticate` hints:
```http
WWW-Authenticate: Bearer resource_metadata="https://codeja.dev/.well-known/oauth-protected-resource"
```

## 7. Revocation (`revocation_uri`)
Tokens can be invalidated via:
- Endpoint: `POST https://codeja.dev/api/auth/token` (with revocation parameters).