# CertbotX

> CertbotX serves both human customers and agent customers over one organization, plan, quota, domain, certificate, deployment, and audit model.

## Discovery

- Agent Card: https://www.certbotx.cn/.well-known/agent-card.json
- Machine guide: https://www.certbotx.cn/ai-agent-guide.md
- Human guide: https://www.certbotx.cn/tools/ai-agent
- Customer console: https://www.certbotx.cn/customer
- China API base: https://www.certbotx.cn/api/v1
- Global API base: https://www.certbotx.com/api/v1

## Recommended authentication for agent customers

- A human organization owner creates an Agent customer identity in Customer Console > Account & Security.
- Exchange `client_id` and `client_secret` at `POST /auth/agent/token` using `grant_type=client_credentials`.
- Use the returned `cba_...` access token as `Authorization: Bearer ...`; tokens expire after 900 seconds.
- Every request revalidates the Agent identity, organization, expiry, and current scopes. Revocation is immediate.
- Existing `cbx_...` API Keys remain supported for backward compatibility.

## Scopes

- `read`
- `domains:write`
- `certificates:write`
- `deployments:write`
- `feedback:write`

Billing mutations, refunds, team management, account security, data deletion, and credential management require a human session.

## Safe operating rules

- Read current state before every mutation and omit `organization_id`.
- Adding a domain automatically creates its DNS-01 CNAME delegation.
- Use stable idempotency keys for ACME orders.
- Do not claim success until the API reaches a terminal success state and public TLS verification matches.
- Require explicit human confirmation for certificate revocation or freeze, material rollback, forced deployment, target deletion, and pausing managed renewal.
- Never expose client secrets, access tokens, API keys, cloud secrets, server passwords, or private keys.