# auth.md - Servicio Técnico Gran Canaria

Cómo se autentican los agentes automáticos en serviciotecnicograncanaria.es.

## Resumen

**Leer no exige credenciales** (`anonymous`): cualquier agente puede consultar las páginas, el Markdown, el llms.txt, el servidor MCP y la API REST sin darse de alta.

**Darse de alta es opcional y no abre contenido nuevo.** Un token OAuth 2.0 (`client_credentials`) solo concede **cuota**: 600 peticiones por minuto en lugar de 60, sobre los mismos datos públicos. Por eso el alta es automática y sin aprobación humana, y un token perdido no es un incidente de seguridad.

## Getting started

- **No API key is needed to read:** every read operation answers without credentials (60 requests per minute per IP).
- **Try it now, no key:** `curl https://serviciotecnicograncanaria.es/wp-json/agentes/v1/get_company_info`
- **Self-serve API keys:** `POST https://serviciotecnicograncanaria.es/oauth/register` returns a `client_id` and a `client_secret` instantly: no form, no human approval and no sales contact. They raise the limit to 600 requests per minute.
- **Sandbox:** the API is read-only over content that is already public, so production is safe to test against and doubles as the sandbox (https://serviciotecnicograncanaria.es/api/sandbox). No call creates, changes, books or charges anything.

## Discover

| Documento | URL |
|---|---|
| Servidor de autorización (RFC 8414, con bloque `agent_auth`) | https://serviciotecnicograncanaria.es/.well-known/oauth-authorization-server |
| Recurso protegido: el sitio (RFC 9728) | https://serviciotecnicograncanaria.es/.well-known/oauth-protected-resource |
| Recurso protegido: la API de contenido | https://serviciotecnicograncanaria.es/.well-known/oauth-protected-resource/wp-json/agentes/v1 |
| Contrato OpenAPI 3.1 | https://serviciotecnicograncanaria.es/openapi.json |
| Ficha del servidor MCP | https://serviciotecnicograncanaria.es/.well-known/mcp/server-card.json |
| Instrucciones para agentes | https://serviciotecnicograncanaria.es/agents.md |

No se publica `/.well-known/openid-configuration`: aquí no hay usuarios, ni login, ni navegador, así que OpenID Connect no aplica.

## Pick a method

| Método (`identity_types_supported`) | Para qué | Credencial |
|---|---|---|
| `anonymous` sin alta | Leer todo, con 60 peticiones por minuto por IP | ninguna |
| `anonymous` con alta automática (OAuth 2.0 `client_credentials`) | Lo mismo, con 600 peticiones por minuto | `client_secret` |

No hay `identity_assertion` (ID-JAG) ni `service_auth` con cuentas: no existen cuentas de usuario a las que vincular un agente.

## Register

Alta dinámica (RFC 7591), sin aprobación humana:

```
curl -X POST https://serviciotecnicograncanaria.es/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"mi-agente"}'
```

Responde 201 con `client_id` y `client_secret`. Guarda el secreto: no se puede volver a consultar. Límite: 5 altas por hora y por IP. Un cliente que pase 180 días sin pedir ningún token se recicla. No se guarda ningún dato de contacto.

## Claim

<a id="reclamar-un-registro"></a>No hay nada que reclamar: el alta es anónima, no cuelga de una cuenta ni de una persona, y un `client_id` es de quien tenga su `client_secret`. Si se pierde, se da de alta otro.

## Exchange

Token de acceso (RFC 6749, sección 4.4), con `client_secret_basic` o `client_secret_post`:

```
curl -u CLIENT_ID:CLIENT_SECRET -X POST https://serviciotecnicograncanaria.es/oauth/token -d grant_type=client_credentials
```

Devuelve un token opaco de tipo Bearer que dura 3600 segundos. Reutilízalo: el endpoint admite 30 peticiones por minuto.

## Use the access_token

```
curl -H 'Authorization: Bearer TOKEN' https://serviciotecnicograncanaria.es/wp-json/agentes/v1/quota
```

Con el token, la API responde igual pero con la cuota ampliada. La única operación de la API que exige token es `/wp-json/agentes/v1/quota`, que informa de la cuota del propio cliente.

Para comprobar el token: `curl -H 'Authorization: Bearer TOKEN' https://serviciotecnicograncanaria.es/agent/identity` devuelve quién eres (`client_id`, scope y cuota). Sin token responde **401** con `WWW-Authenticate` y `resource_metadata`, el camino para autenticarse.

| Scope | Para qué |
|---|---|
| `content:read` | Leer el contenido con la cuota ampliada |
| `quota:read` | Consultar la propia cuota en /quota |

## Errors

- Un token que no vale devuelve **401** con `WWW-Authenticate: Bearer resource_metadata="https://serviciotecnicograncanaria.es/.well-known/oauth-protected-resource/wp-json/agentes/v1", ...` y no se degrada a anónimo en silencio.
- Cuota agotada: **429** con `Retry-After`. Cada respuesta trae `RateLimit-Policy`, `RateLimit`, `RateLimit-Limit`, `RateLimit-Remaining` y `RateLimit-Reset`.
- Errores del servidor OAuth: JSON con `error` y `error_description` (RFC 6749, sección 5.2).

## Revocation

```
curl -u CLIENT_ID:CLIENT_SECRET -X POST https://serviciotecnicograncanaria.es/oauth/revoke -d token=TOKEN
curl -u CLIENT_ID:CLIENT_SECRET -X POST https://serviciotecnicograncanaria.es/oauth/introspect -d token=TOKEN
```

Revocación según RFC 7009 e introspección según RFC 7662. Un cliente solo puede ver y revocar sus propios tokens.

## Escritura

No existe ningún endpoint de escritura público. Un token OAuth de este sitio no concede ningún permiso dentro de WordPress.

## Contacto

Para pedir un servicio o cualquier otra consulta: https://serviciotecnicograncanaria.es/contacto/