本页面记录了 ATH 协议 API 使用的所有请求和响应 Schema。 规范的机器可读 Schema 提供以下格式：

​
发现

​
DiscoveryDocument

由 GET /.well-known/ath.json 返回。 
{
  "ath_version": "0.1",
  "gateway_id": "ath-gateway.example.com",
  "agent_registration_endpoint": "https://ath-gateway.example.com/ath/agents/register",
  "supported_providers": [ProviderInfo]
}
字段类型必填描述
ath_versionstring是协议版本
gateway_idstring是网关标识符
agent_registration_endpointstring (URI)是代理注册 URL
supported_providersProviderInfo[]是可用的服务提供方

​
ProviderInfo

{
  "provider_id": "example-mail",
  "display_name": "Example Mail",
  "categories": ["email", "productivity"],
  "available_scopes": ["mail:read", "mail:send", "mail:delete"],
  "auth_mode": "OAUTH2",
  "agent_approval_required": true
}
字段类型必填描述
provider_idstring是唯一的服务提供方标识符
display_namestring是人类可读的名称
categoriesstring[]否服务提供方分类
available_scopesstring[]是可请求的范围
auth_modestring是认证模式（例如 "OAUTH2"）
agent_approval_requiredboolean是是否需要注册

​
注册

​
AgentRegistrationRequest

发送至 POST /ath/agents/register。 
{
  "agent_id": "https://travel-agent.example.com/.well-known/agent.json",
  "agent_attestation": "<signed JWT>",
  "developer": {
    "name": "Example Corp",
    "id": "dev-example-12345"
  },
  "requested_providers": [
    { "provider_id": "example-mail", "scopes": ["mail:read", "mail:send"] }
  ],
  "purpose": "Travel planning assistant",
  "redirect_uris": ["https://travel-agent.example.com/callback"]
}
字段类型必填描述
agent_idstring (URI)是代理的规范 URI
agent_attestationstring (JWT)是签名的证明令牌
developer.namestring是开发者名称
developer.idstring是开发者标识符
requested_providersarray是请求的服务提供方和范围
purposestring否人类可读的用途说明
redirect_urisstring[]否OAuth 回调 URI。如果提供，授权时通过精确匹配验证。如果省略，user_redirect_uri 必须（MUST）被拒绝

​
AgentRegistrationResponse

{
  "client_id": "ath_travelbot_001",
  "client_secret": "ath_secret_xxxxx",
  "agent_status": "approved",
  "approved_providers": [ProviderApproval],
  "approval_expires": "2027-01-01T00:00:00Z"
}
字段类型描述
client_idstring唯一的注册标识符
client_secretstring令牌交换的密钥
agent_status"approved" | "pending" | "denied"注册状态
approved_providersProviderApproval[]各服务提供方的审批结果
approval_expiresstring (ISO 8601)过期时间戳

​
ProviderApproval

{
  "provider_id": "example-mail",
  "approved_scopes": ["mail:read"],
  "denied_scopes": ["mail:send"],
  "denial_reason": "Send capability requires additional review"
}

​
授权

​
AuthorizationRequest

发送至 POST /ath/authorize。 
{
  "client_id": "ath_travelbot_001",
  "agent_attestation": "<signed JWT>",
  "provider_id": "example-mail",
  "scopes": ["mail:read"],
  "user_redirect_uri": "https://travel-agent.example.com/callback",
  "state": "<random-state-string>",
  "resource": "https://api.example.com/v1"
}
字段类型必填描述
client_idstring是代理的客户端 ID
agent_attestationstring (JWT)是新鲜的证明令牌
provider_idstring是要授权的服务提供方
scopesstring[]是要请求的范围（需在已批准范围内）
user_redirect_uristring (URI)否授权同意后的重定向地址
statestring是CSRF 保护状态值（必须（MUST）使用 CSPRNG 生成，至少 128 位熵）
resourcestring (URI)否目标资源服务器（RFC 8707）

​
AuthorizationResponse

{
  "authorization_url": "https://example.com/oauth/authorize?...&code_challenge=...&code_challenge_method=S256",
  "ath_session_id": "ath_sess_abc123"
}
字段类型描述
authorization_urlstring (URI)包含 PKCE 参数的 OAuth 授权同意 URL
ath_session_idstring用于令牌交换的会话 ID

​
令牌

​
TokenExchangeRequest

发送至 POST /ath/token。需要 client_secret 和新鲜的 agent_attestation 以证明持有代理私钥。 
{
  "grant_type": "authorization_code",
  "client_id": "ath_travelbot_001",
  "client_secret": "ath_secret_xxxxx",
  "agent_attestation": "<signed JWT>",
  "code": "<oauth-authorization-code>",
  "ath_session_id": "ath_sess_abc123"
}

​
TokenResponse

{
  "access_token": "ath_tk_xxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "effective_scopes": ["mail:read"],
  "provider_id": "example-mail",
  "agent_id": "https://travel-agent.example.com/.well-known/agent.json",
  "scope_intersection": {
    "agent_approved": ["mail:read"],
    "user_consented": ["mail:read", "mail:send"],
    "effective": ["mail:read"]
  }
}

​
ScopeIntersection

{
  "agent_approved": ["mail:read"],
  "user_consented": ["mail:read", "mail:send"],
  "effective": ["mail:read"]
}
字段类型描述
agent_approvedstring[]服务为该代理批准的范围
user_consentedstring[]用户同意的范围
effectivestring[]交集（有效权限）

​
吊销

​
TokenRevocationRequest

发送至 POST /ath/revoke。需要客户端认证，按照 RFC 7009。 
{
  "client_id": "ath_travelbot_001",
  "client_secret": "ath_secret_xxxxx",
  "token": "ath_tk_xxxxxxxx"
}

​
错误

​
ATHError

所有错误响应遵循以下结构： 
{
  "code": "INVALID_ATTESTATION",
  "message": "Agent attestation JWT has expired",
  "details": {}
}
错误码HTTP 状态码描述
INVALID_ATTESTATION401代理证明 JWT 验证失败
AGENT_NOT_REGISTERED403代理必须先注册才能授权
AGENT_UNAPPROVED403代理注册被拒绝
PROVIDER_NOT_APPROVED403代理未获得该服务提供方的批准
SCOPE_NOT_APPROVED403代理未获得所请求范围的批准
SESSION_NOT_FOUND400未找到 OAuth 会话
SESSION_EXPIRED400OAuth 会话已过期
STATE_MISMATCH400OAuth state 参数不匹配
TOKEN_INVALID401ATH 访问令牌无效
TOKEN_EXPIRED401ATH 访问令牌已过期
TOKEN_REVOKED401ATH 访问令牌已被吊销
AGENT_IDENTITY_MISMATCH403请求中的代理 ID 与令牌绑定不匹配
PROVIDER_MISMATCH403请求中的服务提供方与令牌绑定不匹配
USER_DENIED403用户拒绝了 OAuth 授权同意
OAUTH_ERROR502上游 OAuth 提供方返回错误
INTERNAL_ERROR500内部服务器错误