# auth.md

Vibeking: accounts and sign-in for AI agents.

## Audience

AI agents and MCP clients (for example ChatGPT, Claude, Codex) that act on behalf of a signed-in Vibeking user. There is no anonymous or autonomous agent account.

## Registration and provisioning

- Client registration: OAuth 2.0 Dynamic Client Registration (RFC 7591) at the endpoint listed as registration_endpoint in the authorization server metadata (see https://vibekingdevelopment.com/.well-known/oauth-protected-resource, then {authorization_server}/.well-known/oauth-authorization-server).
- User accounts are created by people at https://vibekingdevelopment.com/auth with a name, email address and password; the email address is confirmed by email. A forgotten password is reset on the same page.
- No agent self-registration endpoint (no /agent/auth). Agents never create user accounts.

## Supported methods

- oauth2_authorization_code with PKCE (S256), user consent in the browser.
- Scopes: openid, email, profile.

## Credential use

- Send the access token as `Authorization: Bearer <token>` to https://vibekingdevelopment.com/mcp. Tokens in query strings are rejected.
- Refresh with the refresh_token grant at the token_endpoint. Revoke access by signing out or removing the connection.
- Data access is limited to the organizations of the signed-in user and enforced server side.

## Connecting an AI assistant (MCP)

- Endpoint: https://vibekingdevelopment.com/mcp (Streamable HTTP).
- Authentication: OAuth 2.1 bearer tokens.
- Discovery: https://vibekingdevelopment.com/.well-known/oauth-protected-resource lists the authorization server.
- Sign in with your Vibeking account. Data is limited to the organizations of that user.

## Limits

- Without a subscription: 200 MCP calls per month, read actions only.
- Write actions (`update_task_status`, `order_fix`, `start_scan`, `add_keywords`) require an active subscription.
- Calls are counted per organization per month.

## Tools (19)

- `list_sites`: List the websites the signed-in user can access, with organization, platform and language.
- `list_issues`: List issues found for a website, optionally filtered by status and severity.
- `list_tasks`: List fix tasks for a website, including fix and verification instructions.
- `update_task_status` (write): Update the status of a fix task (todo, doing, done or blocked).
- `get_site_metrics`: Summarize daily metrics for a website over the last N days, totalled per source and metric (day totals only). Sources include gsc, ga4, psi, crux, uptime, chatgpt_ads (impressions, clicks, spend in EUR, conversions) and google_ads (impressions, clicks, spend in the ad account currency, conversions, conversion_value).
- `order_fix` (write): Ask Vibeking to carry out the fix for a task, at the catalogue price. You only pay once the fix is proven. Owners and admins of the organization only, and the organization needs an active subscription.
- `get_goals`: Show the goals per metric for a website: current value, previous period, baseline, targets at 3, 6 and 12 months, and whether the goal is on track.
- `get_report`: Return the stored monthly report content for a website and month: key numbers, health, AI visibility, fixes, goals and the three decisions.
- `get_ai_visibility`: Show AI answer visibility for a website: share of answers per engine per week, open answer gaps with the question, engines and cited competitors, and the tracked competitor domains.
- `get_pages`: List the pages of a website with Google clicks over 90 days and, from the latest completed crawl, status code, title, H1, meta description and issues per page.
- `get_keywords`: List Search Console queries for a website over the last 28 days with clicks, impressions, CTR and average position, plus the tracked keywords with their latest ranking.
- `get_fix_plan`: Return the stored AI fix plan of a task, with its steps and when it was generated.
- `get_fix_changes`: Return the change set of a fix order: per page the field, the value before and after, and the status of each change.
- `get_fix_catalog`: List the fixes Vibeking can carry out, with the price in EUR excluding VAT and the title and description in Dutch and English.
- `get_connections`: List the data connections of a website (Search Console, Analytics, Ads, ChatGPT Ads) with status, last sync and error.
- `get_subscription`: Show the plan, subscription status, plan limits and current usage of an organization, including MCP calls this month.
- `start_scan` (write): Start a crawl of a website through the same path and page limits as the Scan now button. Returns the run id, or the reason the scan was refused.
- `get_competitors`: List the competitors of a website with organic keywords, estimated traffic and top 3/top 10 counts (refreshed monthly via DataForSEO), the shared keyword positions, and suggested competitors.
- `add_keywords` (write): Add keywords to daily Google rank tracking for a website (max 80 characters each). Country and language come from the site. Owners and admins only; needs an active subscription and counts toward the plan keyword limit.

## Contact

- info@vibekingdevelopment.com