Conectar una herramienta a tu tienda

Tu ERP, el programa del almacén, un cuadro de mando, un panel propio, un guion que corre de madrugada: todo lo que tenga que leer o cambiar la tienda sin una persona delante entra por un token de servicio.

Una sesión del panel no vale para esto. Es de una persona, caduca, y se muere el día que esa persona se va o cambia su contraseña. Un token de servicio es de la tienda, no de nadie, y solo hace lo que le escribiste.

Crear uno

Panel → Conexiones → Crear token. Esa pantalla solo la ve un administrador.

Eliges tres cosas:

• Un nombre. Para qué es y dónde lo vas a guardar. Es lo único que verás a su lado el día que haya que decidir si se revoca.
• Qué puede hacer. Una línea por área y, en cada una: ninguno, leer o escribir. Todo empieza en ninguno. Escribir incluye leer, así que nunca hace falta dar los dos.
• Cuándo caduca. 30 días, 90 días, un año o nunca. Pon una fecha si puedes: un token sin caducidad hay que revocarlo a mano el día que sobra, y ese día no se acuerda nadie.

Cópialo en ese momento

El token se enseña una vez, en la pantalla donde lo creaste. Después ya no está: la tienda solo guarda una huella SHA-256 suya, así que ni el panel ni la API pueden volver a enseñártelo — no por no querer, sino porque no lo tienen.

Si lo pierdes, lo revocas y creas otro. Ese es todo el procedimiento de recuperación, y es a propósito.

Tiene esta pinta:

pcc_svc_<55 caracteres>

El prefijo pcc_svc_ está ahí para que un buscador de secretos (el de GitHub, el de tu CI, el tuyo) lo reconozca si alguien lo pega donde no debe. Los últimos caracteres son una suma de control, para que un buscador distinga un token de verdad de una cadena cualquiera sin tener que preguntarle a nadie.

Usarlo

Igual que un token de sesión: cabecera Authorization con Bearer.

curl https://mitienda.com/gestion/pedidos \
  -H "Authorization: Bearer pcc_svc_..."

const r = await fetch("https://mitienda.com/gestion/productos", {
  headers: { Authorization: `Bearer ${process.env.PCC_TOKEN}` },
})

Para comprobar que el token sigue vivo y con qué alcance:

curl https://mitienda.com/gestion/quien-soy -H "Authorization: Bearer pcc_svc_..."

{
  "actor_type": "servicio",
  "servicio": {
    "id": "svct_...",
    "nombre": "sincronización del almacén",
    "permisos": { "catalogo": "escribir" }
  }
}

El id es el identificador público del token. No es secreto: es lo que identifica su fila en el panel y en la auditoría.

Cuando dice que no

Si al token le falta un permiso, la tienda contesta 403 y dice cuál:

{ "message": "A este token de servicio le falta «Pedidos y facturas» con permiso de escritura para hacer eso." }

Ese es el aviso que hay que leer antes de ponerse a probar. Añade el área, o el nivel, y vuelve a intentarlo.

Si la respuesta es 401, el token no vale en absoluto: revocado, caducado, mal copiado o inventado. La tienda contesta lo mismo a los cuatro casos a propósito —al otro lado no hay una persona a la que explicarle nada, y distinguir «caducado» de «no existe» solo le sirve a quien está probando tokens a ver cuál cuela—.

Lo que un token no alcanza nunca

Hay partes del panel cerradas a los tokens de servicio, y siguen cerradas marques lo que marques:

• el equipo (/gestion/usuarios, /gestion/create-staff)
• las llaves de las pasarelas de pago y de los proveedores de IA
• las extensiones, que ejecutan código
• las mudanzas desde otra tienda
• el borrado de datos personales
• la entrada de los agentes de IA (/mcp)
• esta misma pantalla: un token no puede emitir más tokens

Todas tienen algo en común: reparten capacidad. Una credencial de larga vida que pueda crear un administrador convierte una fuga de treinta segundos en un acceso permanente, y revocar el token después no lo quita: la cuenta que creó sigue ahí. Así que esa puerta no se abre, ni con una casilla.

Hay una excepción, y hay que confirmarla a mano al crear el token: pagar a autores. Saca dinero de la tienda, así que está marcada como tal y te obliga a decir que sí aposta; pero es una operación acotada y auditada, no un permiso que multiplique permisos, y liquidar a los autores desde un panel propio es justo una de las cosas para las que esto existe.

Cuánto puede llamar

Un token tiene un presupuesto de puntos por minuto, y es suyo: una herramienta que se desboque no se come nunca el de otra.

No todas las peticiones cuestan lo mismo. Leer cuesta 1 y escribir cuesta 5, sobre un único contador, que es como le pone precio GitHub a su API. Leer un catálogo veinte veces por segundo es tráfico normal; escribir veinte pedidos por segundo no lo es, y el daño que hace un token filtrado está casi todo en la escritura.

De fábrica son 1200 puntos por minuto: 1200 lecturas (20 por segundo) o 240 escrituras (4 por segundo). Pagar a autores lleva su propio presupuesto, mucho más corto —sacar dinero nunca es una ráfaga, y una fuga no tiene que convertirse en una tanda de pagos antes de que nadie mire—. Los dos se ponen con variables de entorno (PCC_LIMITE_SERVICIO_PUNTOS, PCC_LIMITE_SERVICIO_PUNTOS_SENSIBLE; ver Variables de entorno).

Cada respuesta te dice por dónde vas, no solo las que dicen que no:

RateLimit-Limit: 1200
RateLimit-Remaining: 1143
RateLimit-Reset: 41
RateLimit-Policy: "servicio";q=1200;w=60
RateLimit: "servicio";r=1143;t=41

Las tres primeras son las que entienden hoy las librerías de cliente; las dos últimas son lo mismo en el formato al que se ha movido el borrador de la IETF. Lee las que quieras y baja el ritmo antes de chocarte.

Cuando se acaba el presupuesto, la respuesta es un 429 con Retry-After en segundos. Espera eso. Reintentar al momento, o en bucle, empeora justo lo que estás sufriendo. Si necesitas repartir la carga, gasta los puntos en lecturas y agrupa las escrituras.

Hay un interruptor para apagarlo del todo (PCC_LIMITE_SERVICIO_ACTIVO=0). Existe para el día que hace falta —traerse una tienda entera, que escribe durante horas— y no como sitio donde esconder un bucle mal escrito.

Ver lo que hace

La lista enseña, por cada token, cuándo se usó por última vez y desde qué dirección, y cuántas peticiones lleva. Eso es todo lo que se guarda: el último uso, no un registro de cada llamada. Basta para contestar las dos preguntas que se hacen —¿esto sigue vivo? y ¿desde dónde llama?— sin juntar un rastro que nadie pidió.

Y enseña en rojo el día que un token se chocó con su límite y cuántas veces lleva. Eso hay que mirarlo. Un token que de pronto llama diez veces más que nunca es, o una herramienta con un bucle, o un token del que alguien tiene una copia, y no hay una tercera explicación. Sale también en la pantalla de inicio del panel, entre las cosas que mirar hoy. Si no sabes explicarlo, revócalo: te cuesta una integración parada una tarde y es lo único que recupera el acceso.

Revocar

Revocar, en la fila del token. Deja de valer en su siguiente petición; no hay caché ni periodo de gracia.

La fila se queda, marcada como revocada. Después de un susto la pregunta nunca es «cómo se llamaba» sino «qué alcanzaba y cuándo llamó por última vez», y borrar la fila es borrar la respuesta.

Revoca un token cuando la herramienta que lo usaba ya no está, cuando se va alguien que tenía una copia, o en cuanto sospeches que ha estado donde no debía.

Reglas que ahorran disgustos

• Un token por herramienta. No uno para todo. El día que haya que revocar uno, quieres tirar una integración, no todas.
• Dale lo mínimo. Si solo lee informes, leer en Informes y nada más.
• Fuera del código. En una variable de entorno o en tu gestor de secretos, nunca en el repositorio y nunca dentro de un tema: el empaquetador de temas se niega a construir un paquete con uno dentro, y un paquete que ya se ha descargado no se puede retirar.
• Ponle caducidad y renuévalo. Renovar es crear uno nuevo, apuntar la herramienta al nuevo y revocar el viejo; entre medias no se rompe nada, porque los dos valen hasta que revocas.

Ver también

• Tu equipo — para personas, no para máquinas
• Que ChatGPT y Claude puedan vender tus productos — la puerta pública y de solo lectura para agentes de IA, que es otra cosa