# HyperGSC auth.md

For AI agents and MCP clients acting on behalf of a HyperGSC user.
HyperGSC supports OAuth dynamic client registration and authorization code with
PKCE S256. User sign-in and explicit browser consent are required before access.

## 1. Discover

Resource: https://hypergsc.com/mcp
Authorization server: https://hypergsc.com
OAuth metadata: https://hypergsc.com/.well-known/oauth-authorization-server
Protected resource metadata: https://hypergsc.com/.well-known/oauth-protected-resource
MCP resource metadata: https://hypergsc.com/.well-known/oauth-protected-resource/mcp

Fetch protected resource metadata, then the advertised authorization server's
metadata. Its `issuer` must match the advertised authorization server.
Read `agent_auth` for the registration method and endpoints.

## 2. Register an OAuth client

Send `POST https://hypergsc.com/register` with `Content-Type: application/json`:

```json
{
  "client_name": "Example Agent",
  "redirect_uris": ["http://127.0.0.1:7777/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "gsc:read"
}
```

Use your client's actual callback: HTTPS or loopback HTTP, without a fragment.
The response is `201 Created` with a `client_id`. Public clients use `none`;
confidential clients may choose `client_secret_post` or `client_secret_basic` and
must securely retain the returned `client_secret` for token and revocation requests.
Client registration alone does not grant access to a user's account.

## 3. Obtain user authorization

Generate a random PKCE `code_verifier` and its base64url SHA-256 `code_challenge`.
Open `https://hypergsc.com/authorize` in the user's browser with these query parameters:
`client_id`, the registered `redirect_uri`, `response_type=code`,
`code_challenge`, `code_challenge_method=S256`, `scope=gsc:read`,
`resource=https://hypergsc.com/mcp`, and an unpredictable `state`.
The user signs in and approves access. Validate callback `state` before using
the returned `code`. Access is limited to properties the user enables.

Subscription sales and billing tools are not exposed over MCP. Manage billing on the website.
Saving or deleting keywords and SEO changes additionally requires registering
and requesting `projects:write` alongside `gsc:read`. Read-only API keys cannot write
project data. These tools store data in HyperGSC and do not change Google properties.

## 4. Exchange and use credentials

Send `POST https://hypergsc.com/token` with `Content-Type: application/x-www-form-urlencoded`
and `grant_type=authorization_code`, `client_id`, `code`, the same `redirect_uri`,
`code_verifier`, and `resource=https://hypergsc.com/mcp`. Confidential clients must use
their registered authentication method: a form `client_secret` for
`client_secret_post`, or HTTP Basic authentication for `client_secret_basic`.

Store the returned `access_token` and `refresh_token` securely. Send the access
token to `https://hypergsc.com/mcp` in the `Authorization: Bearer <access_token>` header.
These agent credentials authorize MCP access; `/api` dashboard routes use the
user's browser session. Never place credentials in URLs or chat messages.

## 5. Refresh and revoke

When the access token expires, send a form-encoded `POST https://hypergsc.com/token` with
`grant_type=refresh_token`, `refresh_token`, `client_id`, and
`resource=https://hypergsc.com/mcp`, using the registered client authentication method.
Refresh tokens rotate: securely replace both tokens with the new response.
If refresh fails with `invalid_grant`, discard the credentials and obtain fresh
user authorization. On MCP `401`, attempt refresh once, then restart discovery
and authorization if access still fails. Respect `Retry-After` on `429` responses.

Send a form-encoded `POST https://hypergsc.com/revoke` with `token` and `client_id`, using
the registered client authentication method. Revoking an access or refresh token
revokes the entire OAuth connection. Users can also revoke connections in Settings.

## Alternative: user-provisioned API key

The user can create a shared read-only API key in **Account → Settings** at
https://hypergsc.com/settings and configure it directly in the client's secure credential
store. Send `Authorization: Bearer <key>` to `https://hypergsc.com/mcp`. API keys cannot
authorize billing changes; the user rotates or revokes them in Settings.
Never ask the user to paste a key or Google credentials into a conversation.

Registration requires user authorization; ID-JAG, verified-email assertions,
anonymous registration, claim ceremonies, and revocation events are not supported.
During passive discovery, only fetch public documents. Do not POST to registration,
token, or revocation endpoints as a probe.

Client setup: https://hypergsc.com/agent-setup/prompt.md