# auth.md

Authentication for AI agents at Fintoc.

Fintoc exposes its payments and financial-data API to AI agents through the
[Model Context Protocol (MCP)](https://docs.fintoc.com/mcp) server at
`https://mcp.fintoc.com`, secured with OAuth 2.1.

## MCP endpoint

- **Endpoint:** `https://mcp.fintoc.com`
- **Transport:** Streamable HTTP
- **Authentication:** OAuth 2.1 (authorization code + PKCE)

## OAuth 2.1

The MCP server is an OAuth-protected resource. Discovery metadata:

- **Protected resource metadata:** `https://mcp.fintoc.com/.well-known/oauth-protected-resource`
- **Authorization server metadata:** `https://api.fintoc.com/.well-known/oauth-authorization-server`

| Endpoint                    | URL                                      |
| --------------------------- | ---------------------------------------- |
| Issuer                      | `https://api.fintoc.com`                 |
| Authorization               | `https://api.fintoc.com/oauth/authorize` |
| Token                       | `https://api.fintoc.com/oauth/token`     |
| Revocation                  | `https://api.fintoc.com/oauth/revoke`    |
| Dynamic client registration | `https://api.fintoc.com/oauth/register`  |

- **Grant types:** `authorization_code`, `refresh_token`
- **PKCE:** required (`S256`)
- **Dynamic Client Registration (RFC 7591):** supported — clients may self-register at the registration endpoint.

## Scopes

Access is scoped. Request only the scopes a task needs:

| Scope                                           | Grants                                       |
| ----------------------------------------------- | -------------------------------------------- |
| `account:view`                                  | List bank accounts                           |
| `account_number:view` / `account_number:manage` | Read / create account numbers                |
| `customer:view` / `customer:manage`             | Read / create customers                      |
| `payment:view` / `payment:manage`               | Read / manage payments and checkout sessions |
| `billing:view`                                  | List invoices                                |
| `link:view`                                     | List bank links                              |
| `entity:view`                                   | List entities                                |
| `transfer:view`                                 | List transfers                               |
| `payout:view`                                   | List payouts                                 |
| `refund:view` / `refund:manage`                 | Read / create / cancel refunds               |
| `webhook_endpoint:view`                         | List webhook endpoints                       |

## Direct API access (non-agent)

For server-to-server integrations outside MCP, Fintoc uses secret API keys.
See the [API documentation](https://docs.fintoc.com/) for details.

## Discovery

- API catalog: `https://www.fintoc.com/.well-known/api-catalog`
- AI catalog: `https://www.fintoc.com/.well-known/ai-catalog.json`
- MCP server card: `https://www.fintoc.com/.well-known/mcp/server-card.json`
- Agent skills: `https://www.fintoc.com/.well-known/agent-skills/index.json`