# auth.md

This document describes how AI agents can register and authenticate with Project O2
(operated by Magic Forest d.o.o.) services.

## Quick Start

Project O2 supports agent registration through standard OAuth 2.0 flows with
extensions for AI agent authentication. Discovery information is available at:

- **OAuth Protected Resource**: [`https://project-o2.org/.well-known/oauth-protected-resource`](https://project-o2.org/.well-known/oauth-protected-resource)
- **OAuth Authorization Server**: [`https://project-o2.org/.well-known/oauth-authorization-server`](https://project-o2.org/.well-known/oauth-authorization-server)
- **OpenID Connect Discovery**: [`https://project-o2.org/.well-known/openid-configuration`](https://project-o2.org/.well-known/openid-configuration)

## Public resources (no authentication needed)

The Project O2 website is public. All pages and the discovery resources below can be
read by AI agents and crawlers without any authentication:

- Company info for AI: https://project-o2.org/llm-info.md
- Structured data: https://project-o2.org/llm-info.json
- Root index for LLMs: https://project-o2.org/llms.txt
- Agent Skills index: https://project-o2.org/.well-known/agent-skills/index.json
- API Catalog: https://project-o2.org/.well-known/api-catalog
- MCP server card: https://project-o2.org/.well-known/mcp/server-card.json
- A2A agent card: https://project-o2.org/.well-known/agent-card.json

## Supported Identity Types

### 1. Identity Assertion (ID-JAG)

Agents can register using identity assertions from trusted identity providers:

1. Obtain a JWT identity assertion from your identity provider
2. POST the assertion to `https://project-o2.org/oauth/register`
3. Receive a signed identity assertion from Project O2
4. Exchange the assertion at `https://project-o2.org/oauth/token` using the JWT bearer grant

**Supported assertion types:**

- `urn:ietf:params:oauth:token-type:id-jag`
- `verified_email`

### 2. Anonymous Registration

Agents can register anonymously and later claim ownership:

1. POST to `https://project-o2.org/oauth/register` with `identity_type: "anonymous"`
2. Receive a pre-claim scoped access token
3. Use the token for limited access
4. Later claim ownership via `https://project-o2.org/oauth/register/claim`

## Available Scopes

- `read` — Read access to public resources
- `write` — Create and modify resources
- `api:access` — General API access

## Credentials

Agents receive OAuth 2.0 credentials:

- **Access Tokens**: Bearer tokens for API authentication
- **Refresh Tokens**: Long-lived tokens for obtaining new access tokens

## Token Lifecycle

### Obtaining Tokens

```
POST https://project-o2.org/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion=<your-identity-assertion>
&scope=read write api:access
```

### Refreshing Tokens

```
POST https://project-o2.org/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=<your-refresh-token>
```

### Revoking Tokens

```
POST https://project-o2.org/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=<token-to-revoke>
&token_type_hint=access_token
```

## Security Considerations

- Always use HTTPS for all API requests
- Store credentials securely
- Rotate refresh tokens regularly
- Implement proper token revocation on agent deactivation
- Validate JWT signatures using the JWKS endpoint: `https://project-o2.org/.well-known/jwks.json`

## OAuth 2.0 Compliance

This implementation follows:

- [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749) — OAuth 2.0 Authorization Framework
- [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009) — OAuth 2.0 Token Revocation
- [RFC 7523](https://www.rfc-editor.org/rfc/rfc7523) — JWT Profile for OAuth 2.0 Client Authentication
- [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414) — OAuth 2.0 Authorization Server Metadata
- [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) — OAuth 2.0 Protected Resource Metadata
- Auth.md specification for agent authentication

## Support & Documentation

- **Company info**: https://project-o2.org/llm-info.md
- **Responsible AI**: https://project-o2.org/en/responsible-ai
- **Contact**: https://project-o2.org/en/contact
- **Email**: info@project-o2.org