Autenticación

​

Cómo se envía la clave

GET /v1/me HTTP/1.1
Host: api.muveya.com
Authorization: Bearer mvy_test_EXAMPLE...

• La clave es una cadena opaca, no un JWT. No intentes decodificarla.
• Authorization: Bearer es el único medio aceptado. No existe un encabezado X-API-Key ni un parámetro de consulta para la clave.
• El nombre del esquema no distingue mayúsculas de minúsculas, pero la clave debe enviarse exactamente como fue emitida, sin comillas ni saltos de línea.

​

Cómo es una clave

mvy_test_<24 letras y dígitos>_<4 letras y dígitos>

​

Una clave, una clínica dental

1. Ninguna solicitud nombra una clínica dental. Ninguna ruta, parámetro ni encabezado de /v1 acepta un id de tenant o de espacio de trabajo. GET /v1/me te dice qué clínica dental lee la clave, como workspaceId.
2. Una clave lee toda la clínica dental. No la limita el acceso a sedes y bodegas que se aplica a los miembros del equipo: dentro de sus scopes, lee todas las sedes y todas las bodegas.
3. Para integrar dos clínicas dentales, usa dos claves. Un registro de otra clínica dental responde 404, exactamente como si no existiera.

​

Obtener una clave

​

Cuando una clave deja de funcionar

• Si se suspende o se retira a ese miembro de la clínica dental, la clave deja de funcionar de inmediato.
• Reactivar al miembro no recupera la clave. La consola lo advierte al reactivar a alguien: las claves de API anteriores a la suspensión siguen cerradas. Pide una clave nueva.
• Si la clínica dental está suspendida, se rechazan todas sus claves.

​

Tu primera llamada: GET /v1/me

curl https://api.muveya.com/v1/me \
  -H "Authorization: Bearer $MUVEYA_API_KEY"

const response = await fetch("https://api.muveya.com/v1/me", {
  headers: { Authorization: `Bearer ${process.env.MUVEYA_API_KEY}` },
});
console.log(response.status, await response.json());

import os
import requests

response = requests.get(
    "https://api.muveya.com/v1/me",
    headers={"Authorization": f"Bearer {os.environ['MUVEYA_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.json())

{
  "workspaceId": "66d0a1f0c0ffee0000000001",
  "environment": "test",
  "scopes": ["clinics:read", "catalog:read", "inventory:read"]
}

​

Mantén las claves en tu servidor

• Guarda la clave en un gestor de secretos o en una variable de entorno del servidor, y léela en tiempo de ejecución.
• Nunca la pongas en código de navegador, una app móvil, una hoja de cálculo compartida, un repositorio de código, una URL, una línea de log o un reporte de errores.
• Usa una clave por integración, para poder revocar una sin detener las demás.
• Cuando hables con soporte sobre una clave, identifícala por su nombre o su prefijo (los primeros 12 caracteres), nunca por la clave completa.
• Si una clave pudo haberse filtrado, pide que la revoquen de inmediato y reemplázala.

​

Rotar una clave

​

Revocar una clave

• La revocación se aplica desde la siguiente solicitud. No hay caché que esperar.
• No se puede deshacer: una clave revocada no vuelve a funcionar. Pide una clave nueva si todavía necesitas acceso.
• El registro de la clave se conserva para la auditoría de tu clínica dental, igual que los eventos de creación y revocación.

​

Respuestas 401 y 403

{
  "type": "https://docs.muveya.com/errors/api_keys.invalid",
  "title": "API key inválida",
  "status": 401,
  "detail": "La API key falta, es inválida, fue revocada o expiró. Envía una key válida como token Bearer e inténtalo de nuevo.",
  "instance": "/v1/me",
  "code": "api_keys.invalid",
  "requestId": "8d0e5b8a-2f4c-4e1b-9a7d-0c3b5e6f7a81"
}

• El 401 es idéntico para todas las causas, a propósito: no revela si una clave existe. Revisa primero el formato del encabezado y luego consulta con el miembro que pidió la clave si fue revocada o si ese miembro sigue activo.
• El 403 no indica qué scope falta. Llama a GET /v1/me, compara los scopes con la tabla de Scopes y pide una clave con los scopes correctos.
• Las solicitudes rechazadas con 401 o 403 no consumen tu presupuesto de límites de uso y no traen encabezados de límite.
• Un registro que pertenece a otra clínica dental responde 404, nunca 403.

​

MCP usa OAuth