# auth.md — Authentication for agents

Botize's MCP server is an OAuth 2.0 protected resource. Authorization code flow with PKCE
(S256), public clients, and Dynamic Client Registration so an agent can register itself
without anyone issuing a key by hand.

## Discovery

- Protected resource (RFC 9728):
  `https://webhook.botize.es/.well-known/oauth-protected-resource`
- Authorization server (RFC 8414):
  `https://botize.com/.well-known/oauth-authorization-server`

The protected resource points at `https://botize.com` as its authorization server. Both
documents are live and authoritative — if anything below disagrees with them, they win.

Endpoints, as currently advertised:

| Purpose | Endpoint |
|---|---|
| Authorization | `https://botize.com/v2/oauth/authorize` |
| Token | `https://botize.com/v2/oauth/token` |
| Client registration | `https://botize.com/v2/oauth/register` |
| Protected resource | `https://webhook.botize.es/mcp` |

Scope: `AGENT_FULL`. Response type: `code`. Grant type: `authorization_code`.
Code challenge method: `S256`. Token endpoint auth method: `none` (public client — send no
client secret).

## 0. Register a client (RFC 7591)

```
POST https://botize.com/v2/oauth/register
Content-Type: application/json

{
  "client_name": "Your agent",
  "redirect_uris": ["YOUR_REDIRECT_URI"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

Returns a `client_id`. Most MCP clients do this step automatically.

## 1. Generate the PKCE pair

```
code_verifier  = base64url(random_bytes(32))
code_challenge = base64url(sha256(code_verifier))
```

## 2. Send the user to the authorization endpoint

```
GET https://botize.com/v2/oauth/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=AGENT_FULL
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
  &state=RANDOM_STATE
```

The user signs in to Botize if they are not already, reviews the permissions and approves.
If they have no account yet, send them to https://botize.com/en/join first.

## 3. Exchange the code for a token

```
POST https://botize.com/v2/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=YOUR_REDIRECT_URI
&client_id=YOUR_CLIENT_ID
&code_verifier=CODE_VERIFIER
```

Send no `client_secret`: the authorization server advertises
`token_endpoint_auth_methods_supported: ["none"]`.

## 4. Call the MCP server

```
POST https://webhook.botize.es/mcp
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
```

Streamable HTTP transport. Without a token the server answers `401` with a
`WWW-Authenticate` header naming the protected-resource metadata, which is the normal way
to discover all of the above at runtime.

## Revoking

The user revokes access at any time from MCP connections in their Botize account
(`https://botize.com/<ln>/mcps`); no action is needed from the agent. After that the server
answers `401` with a `WWW-Authenticate` challenge: nothing visible happens to the user, and
the client is invited to authorize again. There is no separate revocation
endpoint advertised.

## Scope

`AGENT_FULL` is the only scope. Each authorization creates one MCP connection, and what the
assistant can do is the tool list of that connection: a common set (read, create and edit
the user's tasks, run them and see their runs, list linked accounts, look up apps and
methods, search Botize's documentation, and ask for a new tool) plus the tools the user
approves for it. Read the list with `tools/list`; it changes while the client is connected
when the user approves a new tool. It cannot delete tasks, and running or changing one of
the user's tasks can need the user's confirmation, which they give in Botize. It never
exposes the credentials
of the apps the user has connected — those stay inside Botize.

## Shortcut

Most users never need any of this. In an MCP-aware assistant they paste
`https://webhook.botize.es/mcp` into the connectors panel and approve once. From a
terminal:

```
claude mcp add --transport http botize https://webhook.botize.es/mcp
```