Autenticación

Claves secretas

Cada petición lleva una clave secreta en la cabecera Authorization:

GET /v1/me HTTP/1.1
Host: api.totemstudio.ai
Authorization: Bearer tsk_live_…

Una clave secreta empieza por tsk_live_, seguida de un identificador de búsqueda y del secreto propiamente dicho. Totem la muestra una sola vez, al crearla, y solo conserva un resumen irreversible, así que una clave perdida no se puede recuperar: rótala. En Ajustes → Desarrolladores se ven los cuatro últimos caracteres de cada clave para distinguirlas. Una clave no caduca por sí sola: funciona hasta que la rotas o la revocas.

Las claves que empiezan por tsk_test_ están reservadas para futuros entornos de pruebas. Hoy la API las rechaza con 401 invalid_credentials.

Crear una clave

Un administrador del equipo abre Ajustes → Desarrolladores, elige Crear clave API, da un nombre a la integración y confirma el acceso de lectura al equipo actual. En Opciones avanzadas están la descripción opcional, las restricciones por IP y, para un administrador de la familia, más equipos de la organización (en Equipos y la cabecera Totem-Team se explica quién puede gestionar qué). Si el administrador no ha iniciado sesión hace poco, Totem le pide antes que vuelva a hacerlo. Totem muestra entonces la clave secreta de la integración una sola vez. Cópiala directamente en el almacén de secretos de tu servidor.

La API está en Beta y disponible sin invitación. Crear clave API funciona cuando:

• quien crea la clave tiene el rol de administrador del equipo y una dirección de correo electrónico verificada;
• la organización tiene el plan Pro o uno superior, o acceso a la API acordado con Totem;
• el equipo tiene datos (una cuenta solo de facturación no los tiene) y no está desactivado ni archivado;
• el equipo ha completado su configuración legal: un administrador del equipo guarda su política de privacidad, sus finalidades de tratamiento y su sector de actividad en Privacidad y acuerdos;
• por ahora, el equipo no pertenece a un sector de actividad sensible, como el sanitario.

Si no ves Crear clave API, comprueba el rol, la dirección de correo y que el equipo no sea una cuenta solo de facturación; cuando el motivo es el plan, Ajustes lo indica. El botón se desactiva cuando la organización ya tiene 10 integraciones activas. Si Totem rechaza un equipo, Ajustes lo nombra y explica por qué. Si no, contacta con soporte.

Dónde puede guardarse una clave

Una clave lee datos con nivel de administrador, así que guárdala en un servidor que controles:

• en un gestor de secretos o en una variable de entorno que solo pueda leer el proceso que llama a la API;
• nunca en un navegador, en una app móvil, en JavaScript del lado del cliente ni en un repositorio público;
• nunca en una URL, en una línea de registro, en un comando que escribas en una shell ni en una solicitud de soporte.

La API no envía cabeceras CORS y responde 400 secret_key_in_browser a una petición que lleve a la vez una clave secreta y una cabecera Origin. Si una clave ha estado alguna vez en una página web, una app móvil o una extensión del navegador, dala por filtrada: rótala y marca Esta clave puede estar comprometida, como se explica en Rotar y revocar.

Qué puede leer una clave

Todas las claves de la versión 1.0a son de solo lectura y llevan el mismo conjunto fijo de permisos de lectura: no hay nada que elegir. GET /v1/me los enumera en scopes: teams:read, crm:read, calls:read, messages:read y calendar:read. messages:read solo cubre los metadatos de las conversaciones; ningún endpoint devuelve el texto de un mensaje.

Una clave lee todo lo que puede leer un administrador de sus equipos, incluidos los canales y los registros marcados como privados. El administrador que crea la integración lo confirma antes de que se emita la clave. Da a cada integración solo los equipos que necesita.

Equipos y la cabecera Totem-Team

Una integración cubre un equipo o una lista de equipos de la misma organización (una cuenta de facturación y sus subequipos; en Ajustes → Desarrolladores, el ámbito del acceso Equipos elegidos de la familia). La lista es explícita: un equipo nuevo nunca se añade solo. Lo añade un administrador, y se avisa a los administradores que gestionan la integración y a los de cada equipo que cubre.

Quién puede gestionar una integración depende de lo que cubre:

• Un administrador de equipo crea y gestiona una integración para su propio equipo.
• Solo un administrador de la familia puede crear o modificar una integración que cubra varios equipos: un administrador de la cuenta de facturación que figura en ella como administrador de la familia. Los administradores de cada equipo cubierto la ven en Ajustes, en modo de solo lectura.
• Una organización, o un equipo que no pertenece a ninguna, puede tener hasta 10 integraciones activas, contando todos sus equipos. Revoca las que ya no uses para liberar una plaza.

GET /v1/teams lista los equipos que puede leer una clave, cada uno con un identificador que empieza por team_.

• GET /v1/me y GET /v1/teams describen la clave y nunca llevan la cabecera.
• Las peticiones sobre un registro concreto, como GET /v1/leads/{id}, no la necesitan: el identificador del registro ya indica su equipo.
• Las peticiones que leen una colección de un equipo (listas como GET /v1/leads, GET /v1/boards o GET /v1/members, POST /v1/leads/search y GET /v1/sync/changes) usan el único equipo de la clave. Si la clave cubre varios, indica uno en la cabecera Totem-Team:

curl "https://api.totemstudio.ai/v1/leads?limit=50" \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR"

Los ejemplos de la referencia de la API envían Totem-Team: $TOTEM_TEAM_ID en estas peticiones. Con una clave de un solo equipo, deja TOTEM_TEAM_ID sin definir y no envían la cabecera: cURL descarta una cabecera con el valor vacío, y los ejemplos de Node.js y Python comprueban la variable.

Una clave con un solo equipo también puede enviar la cabecera, siempre que indique ese equipo. Qué significa cada respuesta para tu copia del equipo:

• Sin la cabecera, una clave con varios equipos recibe 400 team_required. Una cabecera que no es un identificador de equipo, o que aparece dos veces, recibe 400 invalid_request.
• Un equipo que la clave no cubre, o que ya no existe, recibe 404 team_not_accessible. Consulta GET /v1/teams: si el equipo ya no aparece, borra sus datos y su cursor.
• Una clave de un solo equipo cubre su equipo solo mientras el equipo siga donde estaba al crearse la clave: en la misma organización o fuera de cualquier organización. Si el equipo entra en una organización, sale de ella o pasa a otra, la clave recibe 404 team_not_accessible y GET /v1/teams deja de mostrar el equipo. Revoca la clave en Ajustes → Desarrolladores y crea una nueva.
• Un equipo desactivado o archivado, o cuyo acceso a la API ha pausado Totem, recibe 403 team_state_restricted. Conserva los datos del equipo y su cursor, omítelo en esta ejecución y vuelve a intentarlo más tarde. Un equipo desactivado o un acceso pausado pueden volver; un equipo archivado sigue restringido salvo que Totem lo restaure. Mientras un equipo está restringido, el feed de cambios no entrega nada de él, tampoco eliminaciones, así que, si la restricción dura más de lo que permite tu política de conservación, borra tu copia.
• Por ahora, Totem no exporta los equipos de un sector de actividad sensible, como el sanitario. Un equipo así no se puede añadir a una integración, y una clave que ya lo cubre recibe 403 sector_restricted para él. Omite el equipo: esperar no lo cambia. El feed de cambios no entrega nada de él, tampoco eliminaciones, así que conserva lo que ya tengas solo mientras lo permita tu política de conservación y después borra tu copia.

Lista de IP permitidas

Una integración puede limitarse a un máximo de 20 direcciones IP o rangos en notación CIDR. Una petición desde cualquier otra dirección recibe 403 ip_not_allowed. La lista se configura en Ajustes → Desarrolladores, en Opciones avanzadas al crear la clave o con Editar integración más tarde; cambiarla exige un inicio de sesión reciente.

• La API solo es accesible por IPv4, así que indica las direcciones IPv4 públicas desde las que salen tus peticiones. Hoy una entrada IPv6 nunca coincide.
• Escribe una dirección o un rango por línea. Un rango debe empezar en su dirección de red, como 203.0.113.0/24, y /0 no se admite. Una lista vacía permite cualquier dirección.
• Si tu plataforma no tiene una dirección de salida fija, como muchas plataformas serverless, haz que su tráfico salga antes por una IP estática.
• Después de guardar la lista, llama a GET /v1/me desde el servidor desplegado para comprobarla.

Totem comprueba la dirección después de la clave, así que una clave incorrecta recibe 401 invalid_credentials venga de donde venga.

Rotar y revocar

Rota una clave con Rotar clave para sustituirla. Totem emite una clave nueva y mantiene la antigua en funcionamiento durante el tiempo que elijas en el diálogo: 1 hora, 24 horas (por defecto) o 7 días. Despliega la clave nueva dentro de ese plazo y nada se detiene. Cuando termina ese tiempo, la clave antigua recibe 401 key_expired. Volver a rotar revoca cualquier clave antigua que siga en su periodo de gracia, y el diálogo te pide que lo confirmes.

Para desactivar la clave antigua al instante, marca Esta clave puede estar comprometida al rotarla, o elige más tarde Desactivar ya la clave anterior. La clave antigua recibe entonces 401 invalid_credentials.

Si una clave puede haberse filtrado, rótala y marca Esta clave puede estar comprometida: la clave antigua se revoca al instante, sin periodo de gracia. Después avísanos, como se explica en Soporte.

Revoca una integración con Revocar acceso para detener todas sus claves. Una clave revocada deja de funcionar en un máximo de 5 segundos, y revocar no se puede deshacer. Los datos que ya copiaste siguen en tus sistemas y dejan de recibir eliminaciones de Totem: bórralos, o consérvalos solo mientras lo permitan las normas del propio cliente. En Seguridad y datos personales se explica qué hacer con ellos.

Crear o rotar una clave, añadir un equipo y cambiar la lista de IP permitidas piden al administrador que vuelva a iniciar sesión si no lo ha hecho hace poco. Cada cambio aparece en la Actividad reciente de la integración, y se avisa de cada uno a los administradores que gestionan la integración y a los de cada equipo que cubre, en Totem y por correo electrónico. Revocar y Desactivar ya la clave anterior nunca exigen iniciar sesión: quien puede gestionar la integración puede detenerla al momento.

Intentos fallidos

Totem cuenta los intentos fallidos: las peticiones con una clave que falta, está mal formada, no existe o es incorrecta. A partir de tan solo 60 fallos desde una dirección IP en un minuto, o 20 con una misma clave, Totem puede bloquear esa dirección o esa clave durante 600 segundos. Mientras dura el bloqueo, las peticiones reciben 429 rate_limited con Retry-After igual a la duración completa del bloqueo; el bloqueo puede terminar antes.

Una clave revocada o caducada, una integración que ya no está activa y una petición desde fuera de la lista de IP permitidas no cuentan. Mientras una clave está bloqueada, las peticiones con su secreto real siguen funcionando: solo se rechazan los intentos de adivinarla. Mientras una dirección está bloqueada, se rechazan todas sus peticiones. Si te quedas bloqueado, corrige primero la clave y después espera lo que indica Retry-After antes de volver a intentarlo.

Muchas peticiones sin una clave bien formada desde una misma dirección también pueden hacer que el cortafuegos situado delante de la API responda 429 por sí mismo, sin Retry-After ni cuerpo JSON, durante un máximo de 10 minutos. Detén el bucle, corrige la cabecera y reintenta con espera exponencial, como se explica en Errores.

Errores de autenticación

Cada código enlaza con su explicación completa en la página de Errores.