# betadomain auth.md

betadomain.de is a German domain registrar operated by OnlineBuilders LLC. This document tells AI agents and automated clients how to access betadomain: what works without credentials, how to act on behalf of a user, and where a human has to step in.

## Registration types

betadomain does **not** offer self-service agent registration (no auth.md `/agent/identity` endpoint, no `agent_auth` block). Agents get access in one of three ways:

| Access | Who it is for | How |
| --- | --- | --- |
| Anonymous | Any agent, read-only lookups | No credential. Rate-limited per IP. |
| OAuth 2.1 (on behalf of a user) | AI apps acting for a betadomain customer | Authorization code + PKCE (S256) with Dynamic Client Registration (RFC 7591). The user signs in and consents. |
| Personal access token | A customer's own scripts and agents | The customer creates a token in the portal and hands it to the agent. |

## Discovery

- Protected Resource Metadata (RFC 9728): <https://betadomain.de/.well-known/oauth-protected-resource/api/mcp> (resource `https://betadomain.de/api/mcp`)
- Authorization Server Metadata (RFC 8414): <https://betadomain.de/.well-known/oauth-authorization-server> (issuer `https://betadomain.de`)
- MCP server: `https://betadomain.de/api/mcp` (Streamable HTTP). Server card: <https://betadomain.de/.well-known/mcp/server-card.json>
- REST API (OpenAPI 3.1): <https://betadomain.de/openapi.json>
- API catalog (RFC 9727): <https://betadomain.de/.well-known/api-catalog>

A request to a write tool without a valid token returns `401` with `WWW-Authenticate: Bearer resource_metadata="https://betadomain.de/.well-known/oauth-protected-resource/api/mcp"`.

## OAuth 2.1 flow

1. Register a client: `POST https://betadomain.de/oauth/register/` (RFC 7591). Public clients use `token_endpoint_auth_method: "none"`; `client_secret_post` is also supported.
2. Send the user to `https://betadomain.de/oauth/authorize/` with `response_type=code`, PKCE `code_challenge_method=S256`, the requested `scope` and `resource=https://betadomain.de/api/mcp`. The user signs in with their betadomain account and approves or denies.
3. Exchange the code at `https://betadomain.de/oauth/token/` (`authorization_code`, later `refresh_token`).
4. Call the MCP server with `Authorization: Bearer <access_token>`.

Tokens are opaque. Access tokens live 1 hour, refresh tokens 30 days; refreshing rotates the refresh token. Endpoint URLs end with a trailing slash.

## Scopes

- `mcp:write`: required for every signed-in tool (`list_my_domains`, `get_order_status`, `start_order`). Request it whenever you act on the user's account.
- `mcp:read`: accepted, but currently grants nothing beyond the anonymous tools.

## Tools (MCP)

Anonymous: `domain_check`, `domain_search`, `whois_lookup` (non-personal RDAP data only), `list_tlds`, `tld_price`.
Signed in: `list_my_domains`, `get_order_status`, `start_order`.

Rate limits per IP: 30 requests/minute and 300 per 6 hours for lookups; `whois_lookup` 15/minute and 150 per 6 hours. Signed-in tools are additionally limited per token.

## Personal access tokens

Customers create a token at <https://betadomain.de/account/profile> (section "MCP/API access"). It starts with `bdk_live_`, is shown once, is stored only as a hash, has full account scope and can be revoked there at any time. Send it as `Authorization: Bearer <token>`.

## Where a human is required

`start_order` never charges anyone. It checks availability and price on the server and returns a checkout link (`payment_url`), and where needed an identity verification link. The customer completes payment and verification in the browser.

## Ending access

- Clients can revoke a token themselves (RFC 7009): `POST https://betadomain.de/oauth/revoke/` with `token` and `client_id` (plus `client_secret` for confidential clients). Revoking either token of a pair ends both.
- Customers can disconnect any app in the portal under Profile → Connected apps (<https://betadomain.de/account/profile>). This revokes all of that app's tokens immediately.
- Personal access tokens can be revoked in the same place.

## Pricing, terms, privacy

- Prices (yearly, EUR, plus VAT): <https://betadomain.de/preise/>
- Terms: <https://betadomain.de/agb/>
- Privacy, including the section on AI assistants: <https://betadomain.de/datenschutz/>

## Contact

Integration questions and support by email only: info@betadomain.de. More context for AI systems: <https://betadomain.de/llms.txt>