# BetterShield Hub: connecting an agent

BetterShield Hub connects AI agents to the WordPress sites a workspace manages, over one MCP server at https://hub.bettershield.ai/mcp.
An agent that can't open a browser for OAuth registers itself here, and a person on the hub approves it.

1. Register:

   POST https://hub.bettershield.ai/agent/identity
   Content-Type: application/json

   {"type": "service_auth", "agent_name": "Your agent's name", "scope": "read write", "login_hint": "person@example.com"}

   `scope` is `read`, or `read write` to also make the changes a site allows. `login_hint` is optional: only that address may approve.
   The answer holds `claim.token`, which only you keep, and `claim.attempt.verification_uri`, a link for the person.

2. Give the person the link. They sign in, see your name, the network you registered from and what you ask for, and approve
   for one workspace, reading only if they choose. The hub then shows them a six-digit code. Ask them for it.
   The link waits 10 minutes, and the code is good for 10.

3. Claim:

   POST https://hub.bettershield.ai/agent/identity/claim/complete
   Content-Type: application/json

   {"claim_token": "<claim.token>", "user_code": "123456"}

   The answer holds `identity.access_token` and `identity.refresh_token`, `client_id` and `mcp_url`. Call the MCP server with
   `Authorization: Bearer <access_token>`. When it expires, refresh it at https://hub.bettershield.ai/oauth/token with
   `grant_type=refresh_token`, the refresh token and `client_id`.

5 wrong codes end the registration: register again to start over. Only `service_auth` is taken; `identity_assertion`
answers `issuer_not_enabled`. The person can end the connection on the hub under Agents › Connect at any time.