# Clonesite AI auth.md

Clonesite AI supports agent registration for the Clone API with Auth.md service_auth. Agents can register with a user email, ask the user to confirm a code on Clonesite AI, and then exchange the completed claim for a scoped OAuth bearer token.

## Discover

- REST resource: `/api/v1`
- MCP resource: `/mcp`
- Protected resource metadata: `/.well-known/oauth-protected-resource`
- MCP protected resource metadata: `/.well-known/oauth-protected-resource/mcp`
- Authorization server metadata: `/.well-known/oauth-authorization-server`
- Authorization server: `/api/auth`
- OpenAPI entry: `/openapi.json`
- MCP server card: `/mcp/server-card`

The Clone API returns bearer challenges with resource metadata. Agents may also fetch the protected resource metadata directly.

## Pick a method

Supported agent registration type:

- `service_auth`: the agent supplies the user's email as `login_hint`. Clonesite AI does not issue a credential until the signed-in user confirms the code on a Clonesite-owned page.
- `verified_email`: the same user-claimed email flow is advertised in OAuth Authorization Server metadata as `identity_assertion.assertion_types_supported = verified_email` for Auth.md scanners and agents that model this flow as a verified-email assertion.

Machine-readable metadata is published in the authorization server metadata under `agent_auth`:

- `register_uri`: `/api/auth/agent/identity`
- `identity_endpoint`: `/api/auth/agent/identity`
- `claim_uri`: `/agent/identity/claim`
- `revocation_uri`: `/api/auth/oauth2/revoke`
- `identity_types_supported`: `service_auth`, `identity_assertion`
- `identity_assertion.assertion_types_supported`: `verified_email`
- `credential_types_supported`: `oauth_access_token`

## Register

Send a JSON request to the agent identity endpoint:

```http
POST /api/auth/agent/identity
Content-Type: application/json
```

```json
{
  "type": "service_auth",
  "login_hint": "user@example.com",
  "scope": "clone_requests:create clone_requests:read"
}
```

The response includes a `claim_token` for the agent, a 6-digit `user_code` to show to the user, and a `verification_uri` on Clonesite AI. No access token is issued before the claim is confirmed.

## Claim ceremony

Ask the user to open the `verification_uri` while signed in to Clonesite AI, then enter the `user_code` shown by the agent. The signed-in Clonesite account email must match `login_hint`.

While the user has not confirmed, the token endpoint returns `authorization_pending` for the claim grant. Agents should poll no faster than the `interval` returned in the claim block.

## Exchange

After the user confirms the code, exchange the claim token at the token endpoint:

```http
POST /api/auth/oauth2/token
Content-Type: application/x-www-form-urlencoded
```

```txt
grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=<claim_token>
```

Successful responses are OAuth bearer token responses:

```json
{
  "access_token": "csoat_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "clone_requests:create clone_requests:read"
}
```

## Use the credential

Send the returned access token in the `Authorization` header when calling the REST Clone API or MCP endpoint:

```http
Authorization: Bearer <access_token>
```

Supported Clone API scopes:

- `clone_requests:create`
- `clone_requests:read`
- `source_downloads:create`

Paid API actions, exports, and source-code downloads remain tied to the claimed Clonesite account and credit balance.

## Revocation

Revoke a service_auth access token at the OAuth revocation endpoint:

```http
POST /api/auth/oauth2/revoke
Content-Type: application/x-www-form-urlencoded
```

```txt
token=<access_token>&token_type_hint=access_token
```

## Credential safety

Do not ask users to paste Clonesite AI session cookies, magic links, payment credentials, raw OAuth tokens, or AgentAuth JWTs into an agent chat. Use service_auth registration, OAuth authorization, or a human-created API key from the developers dashboard.