# auth.md — Ascension Group Growth Partners

## Agent Audience

This document describes how AI agents and automated clients register for and obtain credentials to interact with the Ascension Group Growth Partners API surface. The intended audience is AI agents, MCP clients, partner integrations, and third-party orchestration platforms that need authenticated access to Ascension's protected resources (partner portal data, certified-listing pipeline data, CRM contact upsert, and the Seller Certainty System corpus).

## Registration

Agent registration is performed out-of-band via email to a human operator at this time. To register an agent and obtain credentials, send the following to hello@ascensiongroup.io:

- Agent name and version
- Operating organization
- Intended use case (read-only corpus access, write access to CRM, MCP tool invocation, etc.)
- Requested OAuth scopes (see Supported Scopes below)
- Public key (if using private_key_jwt) or callback URL (if using authorization_code grant)
- Contact email for credential rotation and revocation notices

We typically respond within 2 business days with a client_id and credentials.

### Registration Endpoints

- **Out-of-band (current)**: hello@ascensiongroup.io
- **Programmatic (planned)**: https://agents.ascensiongroup.io/oauth/register (Dynamic Client Registration per RFC 7591, advertised in /.well-known/oauth-authorization-server under registration_endpoint)

## Supported Authentication Methods

- **Bearer token** (header) — primary method. Pass `Authorization: Bearer <access_token>` on every request to a protected resource.
- **client_secret_basic** — for confidential clients using HTTP Basic auth at the token endpoint.
- **client_secret_post** — for confidential clients posting credentials in the request body.
- **private_key_jwt** — for high-trust agents that authenticate by signing a JWT with their private key (RS256).

## Supported Scopes

- `openid` — OpenID Connect identity claims
- `profile` — basic profile information about the registered agent
- `email` — contact email associated with the agent
- `agent:read` — read public corpus and MCP server card endpoints
- `agent:invoke` — invoke MCP tools exposed by the Ascension Worker

## Credential Use

Once registered, agents receive a client_id and (for confidential clients) a client_secret. The standard flow is:

1. Agent obtains an access_token from the token endpoint at https://agents.ascensiongroup.io/oauth/token using their chosen grant_type (client_credentials for service-to-service, authorization_code for user-delegated).
2. Agent includes the access_token in the Authorization header (`Authorization: Bearer <token>`) on every request to https://agents.ascensiongroup.io/* protected endpoints.
3. Tokens expire and must be refreshed using a refresh_token (if issued) or re-obtained via client_credentials.
4. Compromised credentials should be reported immediately to hello@ascensiongroup.io for revocation.

## Discovery Metadata

- OpenID Connect discovery: /.well-known/openid-configuration
- OAuth Authorization Server metadata: /.well-known/oauth-authorization-server (contains agent_auth block with register_uri, identity_types_supported, credential_types_supported)
- OAuth Protected Resource metadata: /.well-known/oauth-protected-resource
- A2A Agent Card: /.well-known/agent-card.json
- MCP Server Card: /.well-known/mcp/server-card.json

## Contact

For agent registration, credential rotation, revocation, or security disclosure: hello@ascensiongroup.io

For legal or compliance questions: legal@ascensiongroup.io

For public content access without authentication: see /robots.txt for content-signal directives and /llms.txt for the canonical corpus index. All crawlers and AI agents are welcome to access public content without registration.