# auth.md

How an AI agent or other software gets access to Maturo.

- Resource server: `https://app.maturo.io/mcp` (Model Context Protocol, Streamable HTTP)
- Authorization server: `https://app.maturo.io`
- Human documentation: https://maturo.io/connect

The OAuth metadata documents below are the source of truth. If this file and them disagree, they win.

## Before you start: access is by invitation

Maturo is invite-only. **Agents cannot register, sign up or create accounts or workspaces.** There is no agent self-registration, no anonymous access and no API key you can request here.

To act for someone, that person must already be a Maturo user (owner admin or analyst) in a workspace where Maturo has switched on API and MCP access. If they are not, stop and tell them to ask their Maturo admin or hello@maturo.io. Do not try to work around it.

## 1. Discover

An unauthenticated request to the resource returns `401` with a challenge:

```http
WWW-Authenticate: Bearer realm="OAuth", resource_metadata="https://app.maturo.io/.well-known/oauth-protected-resource/mcp", scope="maturo:read"
```

- Protected Resource Metadata (RFC 9728): `https://app.maturo.io/.well-known/oauth-protected-resource/mcp`
- Authorization Server Metadata (RFC 8414): `https://app.maturo.io/.well-known/oauth-authorization-server`
- MCP Server Card: `https://app.maturo.io/mcp/server-card`

## 2. Register your client

Use one of:

- **Client ID Metadata Document** (preferred): use the HTTPS URL of your client metadata document as `client_id`.
- **Dynamic Client Registration** (RFC 7591): `POST https://app.maturo.io/oauth/register`.

Registering a client does not give access to anything. Only a user's approval does.

## 3. Get the user's approval

Authorization code flow with PKCE (S256 only), as in OAuth 2.1.

- Authorize: `https://app.maturo.io/authorize`
- Token: `https://app.maturo.io/oauth/token`
- Send `resource=https://app.maturo.io/mcp` on both requests.

The user signs in with a one-time email link (no passwords) and then sees a consent page that names your client, the workspace and your redirect host. They choose whether to allow writing. A Maturo staff account picks the workspace there.

Scopes:

| Scope | Grants |
|---|---|
| `maturo:read` | Read the portfolio, companies, history, anonymous peer benchmarks and plays. Always granted on approval |
| `maturo:write` | Add companies and record Analyst-scored assessments. Only if the user ticks it |
| `offline_access` | A refresh token |

## 4. Use the access token

Send `Authorization: Bearer <access_token>` to `https://app.maturo.io/mcp`. Bearer tokens are accepted in the header only.

- Access tokens last one hour. Refresh tokens rotate on every use and lapse after 90 days unused.
- Every call re-checks the user, their role and whether the workspace still has API and MCP access.
- Tools are listed with `tools/list`. Scores you write are always Analyst-scored, one per company per calendar quarter, and marked as coming from a connected app. Confirm scores with the user before recording them.
- Daily limits per workspace: 200 recorded assessments, 100 new companies.

## 5. Errors

| Response | Meaning | What to do |
|---|---|---|
| `401 invalid_token` | Token missing, expired or revoked | Refresh, or run step 3 again |
| `403 insufficient_scope` naming `maturo:write` | The user approved reading only | Ask the user whether to reconnect with write access; run step 3 again |
| Tool result with `isError` mentioning that access is switched off, the workspace is suspended or the user no longer exists | The workspace or user lost access | Tell the user; do not retry |
| Tool result with `isError` about the daily limit | Fair-use limit reached | Stop and try again the next day |

## 6. Revocation

- The user, or an owner admin, can disconnect your client in Maturo under Settings, Connected apps. Maturo can switch API and MCP access off for a workspace.
- Your client can revoke its own tokens at the token endpoint (RFC 7009).
- After revocation, run step 3 again only if the user asks you to.

## Terms

Use is governed by the Maturo.io terms of service, clauses 7.5 to 7.11: https://maturo.io/terms#s7-api