# Auth.md - Frag Fitty Authentication & Agent Access Guide

Welcome to Frag Fitty (https://fragfitty.de). This guide follows the WorkOS `auth.md` standard for AI agents, autonomous crawlers, and API clients.

## Discover

Frag Fitty advertises auth capabilities through standard discovery metadata:

- **Protected Resource Metadata (RFC 9728):** `GET https://fragfitty.de/.well-known/oauth-protected-resource`
- **Authorization Server Metadata (RFC 8414):** `GET https://fragfitty.de/.well-known/oauth-authorization-server`
- **OpenID Connect Discovery:** `GET https://fragfitty.de/.well-known/openid-configuration`
- **Agent Auth Capability:** The Authorization Server metadata contains the standard `agent_auth` declaration.

## Pick a method

1. **Zero-Auth Anonymous Access (Recommended for Agents & Search)**
   - All studio searches, gym details, prices, opening hours, and reviews are public.
   - No API key or signup required.
   - Request formats: `Accept: text/markdown` or `Accept: application/json`.

2. **OAuth 2.0 & Identity Assertion**
   - For partner booking, studio management, and delegated actions.
   - Supported assertion types: `urn:ietf:params:oauth:token-type:id-jag` and `verified_email`.

## Register

Autonomous agents can obtain an ephemeral client or register via `register_uri`:
- **Registration Endpoint:** `POST https://fragfitty.de/oauth/register`
- **Parameters:** `client_name`, `redirect_uris`, `grant_types`

## Claim

For studio owner verification and claiming listings:
- **Claim Endpoint:** `POST https://fragfitty.de/oauth/claim`
- **Verification:** Studio business registration or domain match.

## Use the credential

Include the bearer token in the HTTP Authorization header:
```http
GET /api/studios/search?q=Berlin HTTP/1.1
Host: fragfitty.de
Authorization: Bearer <your-access-token>
```

When authenticating against protected resources, clients receive the challenge:
```http
WWW-Authenticate: Bearer resource_metadata="https://fragfitty.de/.well-known/oauth-protected-resource"
```

## Errors

Unauthenticated or invalid requests return structured error responses with HTTP 401 or 403:
```json
{
  "error": {
    "code": "unauthorized",
    "message": "Authentication required for this resource",
    "resource_metadata": "https://fragfitty.de/.well-known/oauth-protected-resource"
  }
}
```

## Revocation

Tokens and authorizations can be revoked at any time:
- **Revocation Endpoint:** `POST https://fragfitty.de/oauth/revoke`
- **Parameters:** `token`, `token_type_hint`