# auth.md - HAYAA Athletics Agent Registration Discovery

You are an agent. This service publishes agent registration discovery for approved HAYAA integrations: discover -> register -> claim if required -> exchange for an access token -> call approved public API scopes -> handle revocation. Do not attempt private admin paths.

## Step 1 - Discover the Resource

Fetch OAuth Protected Resource Metadata:

~~~http
GET https://hayaaeagles.com/.well-known/oauth-protected-resource
~~~

The resource server is https://hayaaeagles.com/api/v1. Supported scopes are: public:read, registration:write, contact:write, notifications:write. Bearer tokens are sent in the Authorization: Bearer header.

## Step 2 - Discover Agent Registration Metadata

Fetch OAuth Authorization Server metadata:

~~~http
GET https://hayaaeagles.com/.well-known/oauth-authorization-server
~~~

The agent_auth block is the source of truth for agent registration endpoints:

~~~json
{
  "resource": "https://hayaaeagles.com/api/v1",
  "authorization_servers": ["https://hayaaeagles.com"],
  "scopes_supported": ["public:read", "registration:write", "contact:write", "notifications:write"],
  "bearer_methods_supported": ["header"],
  "issuer": "https://hayaaeagles.com",
  "token_endpoint": "https://hayaaeagles.com/api/v1/oauth/token",
  "revocation_endpoint": "https://hayaaeagles.com/api/v1/oauth/revoke",
  "grant_types_supported": [
    "urn:ietf:params:oauth:grant-type:jwt-bearer",
    "urn:workos:agent-auth:grant-type:claim"
  ],
  "agent_auth": {
    "skill": "https://hayaaeagles.com/auth.md",
    "register_uri": "https://hayaaeagles.com/agent/identity",
    "identity_endpoint": "https://hayaaeagles.com/agent/identity",
    "claim_endpoint": "https://hayaaeagles.com/agent/identity/claim",
    "claim_uri": "https://hayaaeagles.com/agent/identity/claim",
    "events_endpoint": "https://hayaaeagles.com/agent/event/notify",
    "revocation_uri": "https://hayaaeagles.com/api/v1/oauth/revoke",
    "identity_types_supported": ["identity_assertion", "service_auth", "anonymous"],
    "identity_assertion": {
      "assertion_types_supported": ["urn:ietf:params:oauth:token-type:id-jag", "verified_email"],
      "credential_types_supported": ["oauth2-bearer-token"],
      "claim_uri": "https://hayaaeagles.com/agent/identity/claim"
    },
    "service_auth": {
      "credential_types_supported": ["oauth2-bearer-token", "oauth2-client-credentials"],
      "claim_uri": "https://hayaaeagles.com/agent/identity/claim"
    },
    "anonymous": {
      "credential_types_supported": ["oauth2-bearer-token"],
      "claim_uri": "https://hayaaeagles.com/agent/identity/claim"
    },
    "events_supported": [
      "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked"
    ]
  }
}
~~~

## Step 3 - Registration Status

Agent credential issuance is not open self-service. Approved integrations should use the discovery metadata above and contact HAYAA before submitting production registration, contact, notification, or payment-related traffic.

Contact or documentation entry point: https://hayaaeagles.com/docs/api

## Step 4 - Use Credentials

When credentials are issued, call the public API with Authorization: Bearer <access_token> and only request the scopes approved for the integration. Do not send production test registrations, payments, or contact messages without approval.

## Revocation and Events

Credential revocation is advertised at https://hayaaeagles.com/api/v1/oauth/revoke. Upstream identity revocation events are advertised at https://hayaaeagles.com/agent/event/notify with the event schema listed in agent_auth.events_supported.