# auth.md · OLA Vital Center

> How an AI agent gets credentials for OLA Vital Center, a membership hair and nail salon in San Luis Potosí, Mexico. OAuth 2.1 with PKCE (S256) and dynamic client registration (RFC 7591). No API keys, no manual sign-up for the agent.

## Before you start: do you need a token?
No. The public MCP server needs no credentials: https://app.olavital.com/api/mcp/publico (tools: `ola_sucursales`, `ola_iniciar_alta`). The public REST API (catalog, locations, public booking) is documented in https://olavital.com/openapi.json.

You need a token only to act for a specific member (book, cancel, read her plan) or for the salon owners.

| Resource | URL | Who authorizes | Protected resource metadata (RFC 9728) |
|---|---|---|---|
| Members MCP | https://app.olavital.com/api/mcp | the member, in the OLA app | https://app.olavital.com/.well-known/oauth-protected-resource |
| Owners MCP | https://app.olavital.com/api/mcp/admin | a salon owner | https://app.olavital.com/.well-known/oauth-protected-resource/api/mcp/admin |

## Step 1 — Discover

### 1a. Fetch the Protected Resource Metadata
Call the resource without a token. It answers `401` with `WWW-Authenticate: Bearer resource_metadata="…", scope="…"`. Fetch that URL (table above, RFC 9728) and read `authorization_servers` and `scopes_supported`.

### 1b. Fetch the Authorization Server metadata
Fetch https://app.olavital.com/.well-known/oauth-authorization-server (RFC 8414). Take every endpoint from there; do not hard-code the example paths below.

The metadata carries an `agent_auth` block (auth.md profile): `skill` points to this document, `identity_endpoint` is https://app.olavital.com/api/agente/identidad and `identity_types_supported` is empty. OLA accepts no agentic registration (anonymous, service_auth or identity_assertion) yet: a `POST` to `identity_endpoint` answers `400` with `anonymous_not_enabled`, `service_auth_not_enabled` or `issuer_not_enabled` and the `registration_endpoint` to use instead. Go to Step 2.

## Step 2 — Pick a method
OLA supports one method: **OAuth 2.1 authorization code with PKCE (S256), after dynamic client registration (RFC 7591)**. The person approves your agent in the OLA app. The `agent_auth` identity types (anonymous, service_auth, identity_assertion) are not enabled, and there are no API keys.

## Step 3 — Register
`POST` to `registration_endpoint` (today https://app.olavital.com/api/oauth/registro) with JSON:

```json
{
  "client_name": "Your agent",
  "redirect_uris": ["https://your-agent.example/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

You get a `client_id` (public client, no secret). Invalid metadata returns `400 {"error":"invalid_client_metadata"}`.

## Step 4 — User approval
Open `authorization_endpoint` (today https://app.olavital.com/oauth/autorizar) with `response_type=code`, `client_id`, `redirect_uri`, `code_challenge` + `code_challenge_method=S256`, `state`, `resource` (the MCP URL, RFC 8707) and `scope`.
The person signs in to the OLA app on its own page, sees your client name and the scopes, and approves. You never see her password. Owners also need their second factor. The redirect carries `code`, `state` and `iss` (RFC 9207): check that `iss` is the issuer from the metadata.

## Step 5 — Exchange the code
`POST` to `token_endpoint` (today https://app.olavital.com/api/oauth/token), form-encoded: `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`, `code_verifier`, `resource`. The response has `access_token`, `refresh_token`, `expires_in` and the granted `scope`.
Renew with `grant_type=refresh_token` at the same endpoint.

## Step 6 — Use the access_token
Send `Authorization: Bearer <access_token>` to the same MCP URL you asked for. A token for the members MCP never works on the owners MCP, and the reverse (audience-bound tokens).
Members MCP tools: `ola_opciones_reserva`, `ola_horarios_disponibles`, `ola_reservar_cita`, `ola_cancelar_cita`, `ola_mi_membresia`, `ola_mi_perfil`, `ola_pagar`.

## Scopes
Ask for the fewest scopes you need. If you send no `scope`, you get the default ones for that resource.

### Members MCP (https://app.olavital.com/api/mcp)
| Scope | Default | What it allows |
|---|---|---|
| `ola.membresia` | yes | Read the member's plan, services left this month, minimal profile and referrals. |
| `ola.citas` | yes | See services, stylists and free slots; book and cancel the member's appointments. |
| `ola.pagos` | no, request it explicitly | Pay an outstanding balance with the member's saved card. Never granted by default: request it explicitly; she confirms every payment. |

### Owners MCP (https://app.olavital.com/api/mcp/admin)
| Scope | Default | What it allows |
|---|---|---|
| `ola.admin` | yes | Owners only: read the salon dashboard (schedule, sales, memberships) without health or tax data, and draft promotions. |
| `ola.admin.acciones` | no, request it explicitly | Owners only: high-risk actions (reschedule, charge, cancel memberships, publish). Each action shows a preview and requires confirmation. |

## Errors
- `401` with `WWW-Authenticate`: missing, expired or wrong-audience token. Renew or authorize again.
- `403` with `WWW-Authenticate: Bearer error="insufficient_scope", scope="…"`: the call needs a scope you were not granted. Ask the person again with that scope.
- OAuth errors use the standard codes (`invalid_request`, `invalid_scope`, `invalid_target`, `invalid_client_metadata`) in a JSON body.
- Payment: `ola_pagar` needs `ola.pagos`, and the member confirms every payment in the app. Never ask for card data.

## Revocation
- The member removes your access in the OLA app: Mi cuenta › Asistentes de IA › Desconectar. Owners: Configuración › Asistentes de IA.
- After that, the access token and the refresh token stop working, and you must register and ask for approval again.
- There is no revocation endpoint for agents yet; if you no longer need access, stop using the tokens and discard them.

## Test mode
Sandbox: https://ola-vital-staging.web.app is staging, the same API with fake data. It never charges or sends messages.
- Public MCP server: https://ola-vital-staging.web.app/api/mcp/publico. The public REST API uses the same paths as /openapi.json.
- OAuth metadata: https://ola-vital-staging.web.app/.well-known/oauth-authorization-server. Client registration works; authorizing needs a staging test account, which cannot be created from the website.
- It may be reset without notice and has a usage limit. Do not keep anything there you need.

---
En español: el agente se registra solo (registro dinámico), la persona autoriza en la app de OLA y puede desconectarlo cuando quiera. Pide solo los alcances que necesitas; `ola.pagos` y `ola.admin.acciones` nunca van por omisión.

Más: https://olavital.com/desarrolladores · https://olavital.com/openapi.json · https://olavital.com/.well-known/ard.json · https://olavital.com/llms.txt
