# 9bot Agent Authentication and Authorization

Version: 1.0.0  
Last reviewed: 2026-08-31  
Protected resource: `https://mcp.9bot.com.br/mcp`

## Purpose

This document explains how an AI client, MCP client, or agent should discover and complete authorization for the public 9bot MCP gateway.

## Discovery endpoints

Use metadata instead of hard-coding authorization routes:

- Protected resource metadata: `https://mcp.9bot.com.br/.well-known/oauth-protected-resource`
- Authorization server metadata: `https://mcp.9bot.com.br/.well-known/oauth-authorization-server`
- MCP metadata: `https://mcp.9bot.com.br/.well-known/mcp`
- MCP Registry manifest: `https://mcp.9bot.com.br/server.json`

The metadata response is the source of truth for current endpoints, supported grant types, PKCE methods, scopes, and registration capabilities.

## Recommended authorization sequence

1. Start with the protected resource URL or the MCP endpoint.
2. Fetch protected resource metadata.
3. Select an advertised authorization server.
4. Fetch authorization server metadata.
5. Use the authorization flow supported by both the client and server.
6. Use PKCE when advertised and required by the client type.
7. Complete the 9bot authorization screen and select only the required access.
8. Store access and refresh credentials in the client's secure credential store.
9. Connect to the MCP endpoint and discover the authorized tools.

## Client registration

Do not assume dynamic client registration is available. Use a `registration_endpoint` only when it is present in authorization server metadata. Otherwise, create the MCP application in the 9bot Dashboard and use the client credentials or configuration issued there.

Dashboard path described by the product guide:

`Dashboard → Settings → MCP`

An administrator can create an application, choose read-only or full access, authorize groups, configure tool rules, and copy the connection information.

## Authorization boundaries

Access can be limited by:

- OAuth scopes;
- read-only or full-access mode;
- authorized WhatsApp groups;
- tool allowlists and denylists;
- sensitive-data policy;
- confirmation requirements;
- tenant subscription and feature availability.

A successful OAuth flow does not imply access to every 9bot tool or group. Always use MCP tool discovery after authorization.

## Credential handling

- Never place access tokens, refresh tokens, authorization codes, client secrets, or confirmation tokens in URLs, prompts, analytics, source control, screenshots, or public logs.
- Use the secure credential manager recommended by the client.
- Rotate or revoke credentials when an integration is no longer needed.
- Treat confirmation artifacts as temporary and single-use.
- Do not share one tenant's credentials with another tenant.

## State-changing operations

Before sending messages, changing moderation state, publishing Workflows, changing schedules, or altering integrations:

1. identify the exact target group;
2. validate the current user's intent;
3. present a concise preview when available;
4. complete explicit confirmation when required;
5. report the server's actual result or job state.

## HTTP authorization failures

- `401 Unauthorized`: authorization is missing, expired, invalid, or not accepted. Use the client's reauthorization or token renewal flow.
- `403 Forbidden`: authorization exists but the scope, group, tool policy, or tenant configuration does not permit the operation.
- `429 Too Many Requests`: respect server retry guidance and avoid duplicate operations.

## Related documentation

- Developer portal: `https://9bot.com.br/developers/`
- API guide: `https://9bot.com.br/developers/api/`
- MCP guide: `https://9bot.com.br/developers/mcp/`
- OpenAPI: `https://9bot.com.br/openapi.json`
- Full AI guidance: `https://9bot.com.br/llms-full.txt`