# auth.md

MetroCheck.ai — agent registration and authentication.

## Audience

AI agents and automated clients that call MetroCheck HTTP APIs under `https://dev-metrocheck-frontend.filip-956.workers.dev/api`.

## Protected resource metadata

- URL: https://dev-metrocheck-frontend.filip-956.workers.dev/.well-known/oauth-protected-resource/api
- Alternate URL: https://dev-metrocheck-frontend.filip-956.workers.dev/.well-known/oauth-protected-resource
- Resource: `https://dev-metrocheck-frontend.filip-956.workers.dev/api`
- Authorization servers: `https://dev-metrocheck-frontend.filip-956.workers.dev`
- Scopes: openid, email
- Bearer methods: header

## Authorization server

- Discovery issuer (RFC 8414 metadata host): `https://dev-metrocheck-frontend.filip-956.workers.dev`
- Token issuer (JWT `iss` from Cognito): `https://metrocheck.auth.us-east-1.amazoncognito.com`
- OpenID configuration: https://dev-metrocheck-frontend.filip-956.workers.dev/.well-known/openid-configuration
- OAuth authorization server: https://dev-metrocheck-frontend.filip-956.workers.dev/.well-known/oauth-authorization-server

## Registration

Humans and agents start at https://dev-metrocheck-frontend.filip-956.workers.dev/register.

1. Create an account or sign in with Cognito Hosted UI (https://dev-metrocheck-frontend.filip-956.workers.dev/login).
2. Complete checkout at https://dev-metrocheck-frontend.filip-956.workers.dev/sales when paid features are required.
3. Obtain an access token from the authorization server token endpoint.
4. Call protected APIs with `Authorization: Bearer <access_token>`.

## agent_auth

```json
{
  "skill": "https://dev-metrocheck-frontend.filip-956.workers.dev/auth.md",
  "register_uri": "https://dev-metrocheck-frontend.filip-956.workers.dev/register",
  "claim_uri": "https://dev-metrocheck-frontend.filip-956.workers.dev/register",
  "identity_types_supported": [
    "anonymous",
    "identity_assertion"
  ],
  "methods": [
    {
      "type": "authorization_code",
      "authorization_endpoint": "https://metrocheck.auth.us-east-1.amazoncognito.com/oauth2/authorize",
      "token_endpoint": "https://metrocheck.auth.us-east-1.amazoncognito.com/oauth2/token",
      "scopes_supported": [
        "openid",
        "email"
      ]
    }
  ],
  "anonymous": {
    "credential_types_supported": [
      "authorization_code"
    ],
    "claim_uri": "https://dev-metrocheck-frontend.filip-956.workers.dev/register"
  },
  "identity_assertion": {
    "assertion_types_supported": [
      "verified_email"
    ],
    "credential_types_supported": [
      "authorization_code"
    ],
    "claim_uri": "https://dev-metrocheck-frontend.filip-956.workers.dev/register"
  },
  "revocation_uri": "https://metrocheck.auth.us-east-1.amazoncognito.com/oauth2/revoke"
}
```

## Token use

Send `Authorization: Bearer <access_token>` on requests to protected `/api/*` routes. On `401 Unauthorized`, read the `WWW-Authenticate` header for `resource_metadata` pointing to OAuth Protected Resource Metadata.

## Documentation

- Service doc: https://dev-metrocheck-frontend.filip-956.workers.dev/auth.md
- OpenAPI: https://dev-metrocheck-frontend.filip-956.workers.dev/.well-known/openapi.json
- API catalog: https://dev-metrocheck-frontend.filip-956.workers.dev/.well-known/api-catalog