# Probator.ai auth.md

How AI agents and the software that runs them authenticate to Probator.ai.

## Who this is for

Agents and applications that call the remote MCP server (`https://probator.ai/mcp`) or the REST API (`https://probator.ai/v1`) on behalf of a Probator.ai account. Access needs a **Pro** or **Team** plan, and every check spends that account's credits.

## Option 1: OAuth 2.1 (recommended for MCP clients and agents)

The user signs in to Probator.ai (email code or passkey) and approves the agent. No key is copied anywhere.

- **Protected resource metadata (RFC 9728):** https://probator.ai/.well-known/oauth-protected-resource/mcp
- **Authorization server metadata (RFC 8414):** https://probator.ai/.well-known/oauth-authorization-server
- **Issuer:** https://probator.ai
- **Authorization endpoint:** https://probator.ai/oauth/authorize (authorization code, PKCE with S256 required)
- **Token endpoint:** https://probator.ai/oauth/token (grants `authorization_code` and `refresh_token`)
- **Registration endpoint (RFC 7591):** https://probator.ai/oauth/register, open, no initial access token
- **Client ID metadata documents:** supported; use an https URL that serves your client metadata as the `client_id` (public clients only)
- **Revocation endpoint (RFC 7009):** https://probator.ai/oauth/revoke
- **Scope:** `checks` (run checks and read the credit balance; no access to saved documents, certificates or account settings)
- **Resource indicator (RFC 8707):** `https://probator.ai/mcp` or `https://probator.ai/v1`

Flow:

1. Call `https://probator.ai/mcp` without credentials. The 401 response carries `WWW-Authenticate: Bearer resource_metadata="https://probator.ai/.well-known/oauth-protected-resource/mcp"`.
2. Register: `POST https://probator.ai/oauth/register` with JSON `{"client_name": "…", "redirect_uris": ["…"], "token_endpoint_auth_method": "none"}`. Redirect URIs must be https, http on a loopback address (any port), or a private-use scheme.
3. Open the authorization URL in the user's browser with `response_type=code`, `client_id`, `redirect_uri`, `code_challenge`, `code_challenge_method=S256`, `state`, `scope=checks` and `resource`. The user signs in and approves; the redirect carries `code`, `state` and `iss`.
4. Exchange the code at the token endpoint with the `code_verifier`. Access tokens (`pb_at_…`) last 1 hour; refresh tokens (`pb_rt_…`) last 30 days and rotate on every use. Reusing an old refresh token ends the authorization.

## Option 2: Agent registration (no OAuth client, no browser on the agent's side)

For agents that act for a person they can talk to. The agent registers with the person's email; the person signs in to Probator and types a 6-digit code the agent shows them. Probator sends no email.

- **Identity endpoint:** `POST https://probator.ai/agent/identity`
- **Claim endpoint:** `POST https://probator.ai/agent/identity/claim` (a new code when the previous one expired)
- **Token endpoint:** https://probator.ai/oauth/token, grants `urn:workos:agent-auth:grant-type:claim` and `urn:ietf:params:oauth:grant-type:jwt-bearer`
- **Supported identity type:** `service_auth` (the person's email as `login_hint`). Anonymous registration and provider-signed ID-JAG assertions are not accepted: checks spend the person's credits, so the person always approves.

Steps:

1. Register:

   ```
   POST https://probator.ai/agent/identity
   Content-Type: application/json

   {"type": "service_auth", "login_hint": "person@example.com", "agent_name": "Your agent's name"}
   ```

   The response has `claim_token` (keep it secret; valid 24 hours) and `claim` with `user_code`, `verification_uri`, `expires_in` (600 seconds) and `interval` (5 seconds).
2. Show the person the `verification_uri` and the `user_code`. They sign in as that email (Pro or Team plan), check the request and type the code.
3. Poll every `interval` seconds:

   ```
   POST https://probator.ai/oauth/token
   Content-Type: application/x-www-form-urlencoded

   grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=clm_…
   ```

   Errors while waiting: `authorization_pending`, `slow_down` (poll less often), `expired_token` (the code expired: `POST /agent/identity/claim` with `{"claim_token", "email"}` for a new code, or register again after 24 hours), `access_denied` (the person declined). On approval, the response is issued once: `access_token` (1 hour), `identity_assertion` and `assertion_expires` (30 days).
4. Renew access without the person: `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>` at the same token endpoint. No refresh tokens are issued.

## Option 3: API key

For scripts and servers without a browser.

- **Provisioning:** the account holder signs in at https://probator.ai/app/?account=api and creates a key under **Account → API**. The full key (`pb_live_…`) is shown once. One key per agent is recommended, named after the agent.
- Give the key to the agent through its secret store or configuration, never in a prompt or a public file.

## Using the credential

Send the access token (from option 1 or 2) or the key as a bearer token on every request:

```
Authorization: Bearer pb_at_… (OAuth) or pb_live_… (API key)
```

- MCP (Streamable HTTP): https://probator.ai/mcp, tools `check_ai`, `check_grammar`, `check_plagiarism`, `check_all`, `get_credits`
- REST API: https://probator.ai/docs/api/ (OpenAPI: https://probator.ai/openapi.json)

## Identity

The agent acts as the account that approved it (options 1 and 2) or created the key. There is no separate agent identity and no anonymous access.

## Scope and limits

- Checks use the account's credits (AI detection 1 credit per word, grammar 1 per 3 words, plagiarism 2 per word). `get_credits` and `GET /v1/usage` are free.
- Rate limit: 60 requests per minute per key or per OAuth authorization (HTTP 429 when exceeded).
- Errors: 401 missing, invalid or expired credential; 402 not enough credits; 403 plan without API access.

## Revocation

The account holder disconnects apps and revokes keys under **Account → API**; both stop working immediately. Apps and agents can revoke their own access tokens at https://probator.ai/oauth/revoke. Report a leaked credential to security@probator.ai.

## More

- Summary for language models: https://probator.ai/llms.txt
- API catalog: https://probator.ai/.well-known/api-catalog