# Convertify auth.md

How an AI agent gets access to Convertify on behalf of a Shopify merchant.

## Audience

AI agents and MCP clients (Claude, ChatGPT, Cursor, custom agents) acting for a merchant who has a Convertify account with a connected Shopify store. An agent cannot create a merchant account or approve access by itself: a signed-in person approves every connection on the consent screen.

## Protected resource

- Resource: https://ai.useconvertify.com/mcp (MCP server, Streamable HTTP)
- Protected resource metadata (RFC 9728): https://ai.useconvertify.com/.well-known/oauth-protected-resource/mcp
- Authorization server metadata (RFC 8414): https://ai.useconvertify.com/.well-known/oauth-authorization-server
- Issuer: https://ai.useconvertify.com

## Register

Two supported methods, both self-serve and free of charge:

1. Dynamic Client Registration (RFC 7591). POST a JSON client metadata document to https://ai.useconvertify.com/oauth/register. Public clients use `token_endpoint_auth_method: "none"` with PKCE. The response contains the `client_id`.
2. Client ID Metadata Document. Use an `https` URL that serves your client metadata as the `client_id`; no registration call is needed.

```http
POST https://ai.useconvertify.com/oauth/register
Content-Type: application/json

{
  "client_name": "My agent",
  "redirect_uris": ["http://127.0.0.1:8976/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

## Sign in

OAuth 2.1 authorization code flow with PKCE (`S256` is required).

1. Send the user to https://ai.useconvertify.com/oauth/authorize with `response_type=code`, `client_id`, `redirect_uri`, `code_challenge`, `code_challenge_method=S256`, `scope`, `state` and `resource=https://ai.useconvertify.com/mcp`.
2. The user signs in to Convertify, picks the stores the connection may reach and approves the scopes.
3. Exchange the code at https://ai.useconvertify.com/oauth/token with the `code_verifier`.
4. Refresh with `grant_type=refresh_token` at the same endpoint. Refresh tokens rotate. Revoke at https://ai.useconvertify.com/oauth/revoke.

## Scopes

- `convertify:read`: View tests, GMPV analytics, behavioral data, campaigns, and store settings.
- `convertify:tests:write`: Draft, launch, stop, update, and delete A/B tests and conflict groups.
- `convertify:settings:write`: Update recording settings, saved funnels/cohorts, the web pixel, and campaign sync.
- `convertify:ai`: Generate AI summaries, briefings, and chat grounded in your data (spends AI credits).

Ask for the least you need. `convertify:read` is granted by default; write and AI scopes are opt-in at consent. A tool that needs a scope you do not hold answers `403 insufficient_scope`.

## Use the credential

Send the access token as `Authorization: Bearer <token>` on every request to https://ai.useconvertify.com/mcp. Access tokens are short-lived. A `401` carries a `WWW-Authenticate` header pointing at the protected resource metadata. Tokens are scoped to the stores the user selected; pass an explicit `store_id` to store-scoped tools.

## Requirements and limits

- The merchant needs a Convertify plan with MCP access (Growth or Pro). Every plan starts with a 7-day free trial. Install from the Shopify App Store: https://apps.shopify.com/convertify-1
- Merchants review and revoke connections in Convertify under Settings, Connections.
- Questions: support@useconvertify.com
- More: https://useconvertify.com/developers and https://useconvertify.com/llms.txt