Autenticación

Toda llamada a la API de Tylode necesita un token. Para tus propios scripts, el servidor MCP y herramientas personales, usa un token de acceso personal; para apps que otras personas conectan a su cuenta, usa OAuth.

#Tokens de acceso personal Pro

Un token de acceso personal actúa como tú, con todo lo que puedes hacer en la app y en todos tus espacios de trabajo. Tiene esta pinta:

tylode_pat_Q2x5b0x7bVJ3dFp6c2hLd0R1a0N2bXhQeU5aT2dIc1E

Los tokens no caducan. Siguen funcionando hasta que los revocas o hasta que tu cuenta deja de estar en Pro.

#Crear un token

1. Abre Ajustes → API y webhooks → API y plugins (ir allí).
2. En Tokens de acceso personal, escribe un nombre que te diga dónde lo vas a usar, como «MCP local» o «Script de facturas».
3. Pulsa Crear token.
4. Cópialo en ese momento. Como avisa la app, no podrás volver a verlo después de cerrar el aviso. Si lo pierdes, revócalo y crea otro.

Si tu cuenta está en Free, en lugar del formulario verás una invitación a cambiar de plan. Mira Planes.

#Ver y revocar tus tokens

La lista de Tokens de acceso personal muestra de cada token su nombre, los primeros caracteres (tylode_pat_Q2x5b…), la fecha de creación y la del último uso. Los que no has usado nunca no tienen fecha de último uso, así que es fácil ver cuáles sobran.

Para revocar un token, pulsa el icono de la papelera (Revocar token) y vuelve a pulsar para confirmar. Deja de funcionar en la siguiente petición. Revocar no se puede deshacer.

#El plan se comprueba en cada petición

Los tokens necesitan que tu cuenta esté en Pro o Premium, y Tylode lo comprueba en cada petición, no solo al crear el token. Si pasas a Free, tus tokens siguen en la lista pero todas las llamadas devuelven 403. Cuando vuelves a Pro, los mismos tokens funcionan otra vez sin tocar nada.

#Enviar el token

Pon el token en la cabecera Authorization con el esquema Bearer:

Authorization: Bearer tylode_pat_xxx

curl https://app.tylode.com/api/v1/workspaces \
  -H "Authorization: Bearer tylode_pat_xxx"

const res = await fetch("https://app.tylode.com/api/v1/workspaces", {
  headers: { Authorization: `Bearer ${process.env.TYLODE_TOKEN}` },
});

import os, requests

res = requests.get(
    "https://app.tylode.com/api/v1/workspaces",
    headers={"Authorization": f"Bearer {os.environ['TYLODE_TOKEN']}"},
)

El token no se acepta en la URL ni en el cuerpo; solo en la cabecera.

#Guarda bien tus tokens

Un token de acceso personal puede leer y cambiar todo lo que puedes tú: cada página, tablero, chat e hilo de correo de todos tus espacios. Trátalo como una contraseña.

• Fuera del código. Cárgalo desde una variable de entorno o un gestor de secretos, y no lo subas nunca a un repositorio.
• Nunca en el navegador ni en una app. Cualquiera puede leer lo que va en el código de una web o en el paquete de una app móvil. Llama a la API desde un servidor; para construir algo dentro de Tylode, escribe un plugin.
• Un token por integración. Si uno se filtra o dejas de usar una herramienta, revocas ese token sin romper los demás.
• Repasa la lista de vez en cuando. Revoca los que no reconozcas o lleves mucho tiempo sin usar.
• Si un token se filtra, revócalo al momento y crea uno nuevo.
• ¿Construyes para otras personas? Usa OAuth. No pidas nunca a otros usuarios su token personal.

#Tokens de OAuth

Las apps registradas con OAuth reciben tokens que empiezan por tylode_oat_. Se envían en la misma cabecera Authorization: Bearer, pero solo pueden llamar a los endpoints que cubren los permisos que concedió el usuario (las bases de datos incluidas, con databases:read y databases:write). En el servidor MCP, el asistente solo ve las herramientas de esos permisos. Quien autorizó la app tiene que estar en Pro.

#Límites de uso

La API admite 60 peticiones por minuto y usuario.

• La cuenta es por persona, no por token. Todos tus tokens, el servidor MCP, las apps OAuth que has autorizado y los plugins que usas comparten las mismas 60.
• El minuto es el del reloj: el contador vuelve a cero en el segundo 0 de cada minuto.
• Las peticiones que se pasan del límite también cuentan, así que insistir mientras estás bloqueado no ayuda.
• Cada llamada a una herramienta MCP cuenta como 1 petición (list_cards, como 2), así que un asistente puede hacer unas 60 por minuto. Conectarse y listar las herramientas tienen su propio límite, aparte. Mira Servidor MCP.
• El endpoint de tokens de OAuth tiene su propio límite: 30 peticiones por minuto y dirección IP.

Si te pasas, recibes un estado 429:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
X-RateLimit-Limit: 60

{ "error": "…" }

Retry-After dice cuántos segundos esperar como mucho y X-RateLimit-Limit, el límite por minuto. Espera a que empiece el minuto siguiente y reintenta, con un pequeño margen creciente si vuelve a pasar. Un 429 significa que no se hizo nada, así que puedes repetir sin miedo cualquier petición que lo reciba, incluidos los POST.

async function tylode(path, init = {}, attempt = 0) {
  const res = await fetch(`https://app.tylode.com/api/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.TYLODE_TOKEN}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });

  if (res.status === 429 && attempt < 3) {
    // Espera al siguiente minuto del reloj, más un margen creciente y algo aleatorio.
    const untilNextMinute = 60_000 - (Date.now() % 60_000);
    const backoff = attempt * 2_000 + Math.random() * 1_000;
    await new Promise((resolve) => setTimeout(resolve, untilNextMinute + backoff));
    return tylode(path, init, attempt + 1);
  }

  const json = await res.json();
  if (!res.ok) throw new Error(`${res.status}: ${json.error}`);
  return json.data;
}

#Errores de autenticación

Los dos devuelven el cuerpo de error habitual. El mensaje es texto para personas y puede cambiar, así que fíjate en el código de estado, no en el texto:

curl -i https://app.tylode.com/api/v1/workspaces \
  -H "Authorization: Bearer tylode_pat_wrong"

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{ "error": "…" }

Tienes más códigos en Errores y convenciones.

#Páginas relacionadas

• Plataforma para desarrolladores: inicio rápido e índice de endpoints.
• Apps OAuth 2.0: acceso en nombre de otros usuarios.
• Seguridad de la cuenta: protege la cuenta que hay detrás de tus tokens.