# MicoRadar auth.md

You are an agent. MicoRadar forecasts wild mushrooms across Spain — where and when each species is likely to fruit — and serves it to assistants over MCP at `https://micoradar.com/mcp`. This document tells you how to get a token for that server on behalf of a person.

There are two ways in. Pick one:

1. **You can open a browser for the person** → use standard OAuth: discovery at `https://micoradar.com/.well-known/oauth-protected-resource`, dynamic client registration, authorization code with PKCE. Every MCP client that supports OAuth does this on its own after the 401 from `https://micoradar.com/mcp`; you do not need the rest of this document.
2. **You only have the person's email address** → use agentic registration with a verified email, below. MicoRadar mails the person a 6-digit code; they read it back to you; you trade it for a token.

There is no anonymous registration and no ID-JAG trust list.

## Step 1 — Discover

```http
GET https://micoradar.com/.well-known/oauth-protected-resource
```

Gives `resource`, `authorization_servers`, `scopes_supported` (`mcp:use`) and `bearer_methods_supported` (`header`).

```http
GET https://micoradar.com/.well-known/oauth-authorization-server
```

The `agent_auth` block names this document (`skill`), the registration endpoint (`register_uri`, also published as `identity_endpoint`) and the claim endpoint (`claim_uri`, also `claim_endpoint`). `identity_assertion.assertion_types_supported` is `["verified_email"]`; the credential is an `access_token`.

## Step 2 — Ask the person

Before you send their address, tell them: MicoRadar will email them a code, and if the address has no MicoRadar account yet, using the code opens a free one and accepts the terms of use (https://micoradar.com/en/terms). Send nothing they have not agreed to.

## Step 3 — Register

```http
POST https://micoradar.com/agent/auth
Content-Type: application/json

{
  "type": "identity_assertion",
  "assertion_type": "verified_email",
  "email": "person@example.com",
  "agent_name": "Your assistant's name",
  "locale": "es"
}
```

`{"type": "service_auth", "login_hint": "person@example.com"}` is accepted too. `agent_name` (shown in the email and on the token) and `name` (for a new account) are optional; `locale` is one of `es`, `ca`, `en`, `ru` and decides the language of the email and of a new account — leave it out and `Accept-Language` decides.

Response `200`:

```json
{
  "registration_id": "reg_…",
  "registration_type": "identity_assertion",
  "assertion_type": "verified_email",
  "claim_uri": "https://micoradar.com/agent/auth/claim",
  "claim_token": "clm_…",
  "claim_token_expires": "2026-10-15T12:10:00Z",
  "post_claim_scopes": ["mcp:use"],
  "claim": { "delivery": "email", "user_code_length": 6, "expires_in": 600, "max_attempts": 5 }
}
```

The answer is the same whether or not the address already has an account. Hold `claim_token` in memory; it is returned once and is useless after the claim.

## Step 4 — Claim

The code goes from MicoRadar to the person by email, and from the person to you. Ask them for the 6-digit code from the email titled "Your MicoRadar code" (in their language). Then:

```http
POST https://micoradar.com/agent/auth/claim
Content-Type: application/json

{ "claim_token": "clm_…", "user_code": "123456" }
```

Response `200`:

```json
{
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "scope": "mcp:use",
  "resource": "https://micoradar.com/mcp",
  "account_created": false
}
```

A wrong code answers `400 invalid_user_code` with `attempts_remaining`; ask the person to check the email again. After five wrong codes, or ten minutes, the claim is gone: register again for a new code.

## Step 5 — Use the token

```http
POST https://micoradar.com/mcp
Authorization: Bearer <access_token>
```

The token lasts 30 days. There is no refresh token: when it expires, or on a `401`, register again.

What the token opens depends on the person's plan, exactly as on the website. While MicoRadar is open to assistants on the Pro plan only, every tool except `my-account` answers with `locked: true` and an `upgrade_url` for an account without Pro — give the person that link rather than working around it.

## Errors

| Code | Where | What to do |
| --- | --- | --- |
| `anonymous_not_enabled` | `https://micoradar.com/agent/auth` | Use the person's email address. |
| `issuer_not_enabled` | `https://micoradar.com/agent/auth` | Only `verified_email` assertions are accepted. |
| `invalid_request` | `https://micoradar.com/agent/auth` | Fix the body: `type`, a valid `email`, a known `locale`. |
| `rate_limited` (429) | `https://micoradar.com/agent/auth` | Three codes per address per 15 minutes, ten per day. Wait `retry_after` seconds. |
| `invalid_claim_token` | `https://micoradar.com/agent/auth/claim` | Wrong, spent or expired token. Register again. |
| `invalid_user_code` | `https://micoradar.com/agent/auth/claim` | Ask the person for the code again. |
| `claim_expired` (410) | `https://micoradar.com/agent/auth/claim` | Too many wrong codes. Register again. |

Back off on `5xx`; do not resend the same body after any other `4xx`.

## Safety

MicoRadar never says a mushroom is safe to eat, and neither should you on the strength of its data. Identification needs the mushroom in hand and someone who knows it.