# auth.md

How an AI agent authenticates with Vynix (https://mcp.vynix.in), the visual
website feedback platform for AI coding agents.

Vynix exposes annotation data to agents in two ways: a hosted OAuth-protected MCP
resource and a local stdio MCP server. The primary auth path is OAuth 2.1
Authorization Code + PKCE. A personal API token remains available as a fallback
for local setups.

## Primary auth: OAuth 2.1 + PKCE

Supported grant types: `authorization_code`, `refresh_token`

Required client behavior:

1. Start authorization at `https://mcp.vynix.in/api/v1/mcp/oauth/authorize`
2. Use `response_type=code`, `client_id`, `redirect_uri`, `scope=mcp`
3. Use PKCE with `code_challenge_method=S256`
4. Exchange the code at `https://mcp.vynix.in/api/v1/mcp/oauth/token`
5. Send the returned bearer token in `Authorization: Bearer <token>`
6. When the access token expires, call the same token endpoint with
    `grant_type=refresh_token`, `client_id`, and the issued `refresh_token`

Refresh token notes:

- Refresh grant responses include a rotated refresh token. Replace the stored
   token after every successful refresh.
- Invalid, expired, revoked, or replayed refresh tokens return `400 invalid_grant`.

Authorization is granted only when the signed-in Vynix user has MCP access in
their subscription.

Machine-readable discovery:

- Protected resource metadata: https://mcp.vynix.in/.well-known/oauth-protected-resource
- Authorization server metadata: https://mcp.vynix.in/.well-known/oauth-authorization-server
- MCP server card: https://mcp.vynix.in/.well-known/mcp/server-card.json
- API catalog: https://mcp.vynix.in/.well-known/api-catalog
- Agent skills: https://mcp.vynix.in/.well-known/agent-skills/index.json

## Secondary auth: personal API token fallback

For local stdio MCP clients, users can still create a revocable personal token
and pass it as `VYNIX_API_TOKEN`.

Create/list/revoke endpoints (session-authenticated):

   POST   https://mcp.vynix.in/api/v1/auth/api-token
   GET    https://mcp.vynix.in/api/v1/auth/api-tokens
   DELETE https://mcp.vynix.in/api/v1/auth/api-tokens/{id}

## Use the existing tooling first

1. MCP server: if you are an MCP client (Claude, Cursor, VS Code, Codex), the
   official server is `@usevynix/mcp-server` (stdio, run via npx). The user
   configures it once with OAuth or a personal token; you call the tools without
   handling raw credentials in chat.
2. REST API: documented at https://mcp.vynix.in/auth.md and in the API
   catalog above.

If the MCP server is already configured in your environment, use it and stop.

MCP server (stdio, run by your agent via npx):

    command: npx -y @usevynix/mcp-server
    env:     VYNIX_API_TOKEN=<token>
             VYNIX_API_URL=https://mcp.vynix.in

Read the token from the environment at the moment of the call. Do not echo it
back to the user, log it, or include it in commit messages or error reports.

## Errors and revocation

| Status | Meaning | What to do |
| --- | --- | --- |
| 400 | OAuth request is invalid (`invalid_request` / `invalid_grant`). | Re-run authorization with valid PKCE fields. |
| 401 | Bearer token missing, malformed, revoked or expired. | Re-authorize or create a fresh personal token. |
| 403 | Plan does not include MCP/API access, or demo account. | Ask the user to upgrade at https://www.vynix.in/pricing/. |
| 429 | Rate limited. | Back off and retry. |

The user revokes tokens at https://www.vynix.in/settings/mcp. Treat a 401 on a
previously working token as revocation: drop it and ask the user to refresh it.