Skip to content
ver .md sin procesar

Autenticación y scopes para Plan

Qué credenciales llegan a la API de Dailybot Plan (Beta): sesiones, API keys personales que actúan como su persona, keys de agente y de la organización, scopes, invitados y privacidad.

Beta

Plan está en beta. Todo lo que está bajo /plan en la aplicación web, los comandos del CLI y de la agent skill para proyectos, objetivos, tableros y tareas, y la API pública /v1/plan/ puede cambiar antes de la disponibilidad general. ¿Quieres probarlo con tu equipo? Escribe a [email protected].

La API de Plan acepta tres credenciales. Se comportan distinto, así que elige la que corresponda a quien actúa. Las reglas generales de toda la API de Dailybot están en Autenticación y Autenticación del CLI; esta página cubre lo específico de Plan.

Tres credenciales

Credencial Cómo se envía Actúa como Úsala para
Sesión iniciada Authorization: Bearer <token> (la app web, o dailybot login para el CLI) Tú, con tu rol La app web de Dailybot, y scripts y agentes que trabajan en nombre de una persona
API key personal X-API-KEY: <key> La persona que la creó, para sí misma Scripts, CI y agentes que deben ser esa persona
Key de agente o de la organización X-API-KEY: <key> Un actor del sistema: sin una persona detrás Integraciones servidor a servidor que leen o escriben trabajo visible para la organización

Sesión iniciada: actúa como tú

Una sesión iniciada lleva tu identidad y tu rol en la organización. dailybot login obtiene una con un código de un solo uso enviado por correo; el mismo flujo está disponible por HTTP (consulta el inicio rápido). Un token de login solo viaja al host de la API que lo emitió.

curl -sS "https://api.dailybot.com/v1/plan/me/tasks/" \
  -H "Authorization: Bearer $DAILYBOT_TOKEN"

API key personal: actúa como su persona

Una API key personal la crea una persona para sí misma. En Plan responde exactamente como esa persona en la app web:

  • Ve lo que ve la persona, incluidos los tableros privados a los que pertenece. me es la persona, y cada escritura se registra como la persona.
  • Puede hacer todo lo que la persona puede hacer en cada endpoint de Plan: todas las lecturas y todas las escrituras de tareas, y todas las escrituras de estructura y membresías: proyectos, tableros, columnas, objetivos, hitos, miembros (por usuario o equipo), participantes, silenciar, vistas guardadas y adjuntos.
  • No hay prerrequisito de administrador de la organización ni scope que pedir: todo miembro no invitado puede, así que su key también.
  • Una key cuya fila lleva scopes tasks:* explícitos tiene un techo que eligió la persona: tasks:write cubre también las operaciones de administración, y tasks:read deja la key en solo lectura. Una key con solo scopes ajenos a Plan no tiene acceso a Plan.
curl -sS "https://api.dailybot.com/v1/plan/me/tasks/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY"

Key de agente o de la organización: un actor del sistema

Una key sin una persona detrás nunca actúa como una persona:

  • Solo ve tableros visibles para la organización, nunca tableros exclusivos para miembros.
  • No tiene me: ?owner=me responde 400 actor_required.
  • Los endpoints que requieren una persona o un administrador (listados más abajo) responden 403 insufficient_scope.
  • Debe tener sus propios scopes de Plan (tasks:read y tasks:write).
  • Actúa como una persona específica solo cuando la solicitud también lleva un exchange token (X-EXCHANGE-TOKEN), como se describe en Autenticación.
  • No puede nombrar a un agente en una escritura: enviar un nombre de agente con una key de agente es 400 invalid_agent_attribution.
curl -sS "https://api.dailybot.com/v1/plan/boards/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY"

Las keys de agente y de la organización necesitan scopes de Plan habilitados. Una key nueva no tiene ninguno. Durante la Beta, escribe a [email protected] para habilitarlos.

Los invitados están limitados por su rol con una key o una sesión por igual: 403 guest_not_allowed, antes de revisar cualquier otra cosa. Una key vencida es 401 credential_expired; una key revocada o un dueño desactivado también es 401 (consulta los errores de inicio de sesión).

Scopes

Scope Otorga
tasks:read Todas las lecturas
tasks:write Escrituras de fila: tareas, comentarios, etiquetas, relaciones, participantes. En la fila de una key cubre también las operaciones de administración de abajo
tasks:admin Escrituras de contenedores: proyectos, tableros, estados, membresías, objetivos. Todo miembro no invitado lo tiene

Cada endpoint de la referencia indica su scope. Cómo los obtiene cada credencial:

Credencial Scopes
Sesión iniciada, miembro no invitado tasks:read, tasks:write, tasks:admin
API key personal Todo lo que puede hacer su persona, sin otorgar nada. Si la fila de la key lista scopes de Plan explícitos, son un techo
Key de agente o de la organización Solo los scopes otorgados a la key (tasks:read, tasks:write); se rechaza en los endpoints que requieren una persona
Invitado, con cualquier credencial Ninguno: se rechaza con 403 guest_not_allowed antes del entitlement

Una llamada sin el scope que necesita responde 403 insufficient_scope.

La privacidad es la membresía (invitación), no el rol de la organización. Los contenedores de toda la organización son un espacio compartido. Un proyecto, tablero o tarea members responde 404 not found a quien no tiene un grant, en lecturas, listas, búsqueda, comentarios, adjuntos y actividad por igual. Trátalo como no visible, nunca como «no permitido». Un tablero dentro de un proyecto members sigue la membresía del proyecto, y los tableros exponen effective_visibility (org o members) para distinguirlo. Invita a una persona o a un equipo con escrituras de membresía para compartir; el último grant en un contenedor privado es 409 last_grant_cannot_be_removed. No hay roles por proyecto como lead o viewer: la membresía es solo un grant.

Supervisión. Los administradores de la organización y los managers de todos los equipos pueden ver todos los proyectos. Un tablero members sigue necesitando un grant explícito.

Los invitados se rechazan antes de revisar cualquier otra cosa, así que un invitado nunca sabe si la organización tiene Plan habilitado ni qué tan cerca está de los límites de su plan.

Endpoints que requieren una persona

Algunos endpoints necesitan una persona detrás de la solicitud, así que una key de agente o de la organización se rechaza con 403 insufficient_scope. Una sesión iniciada y una API key personal funcionan en todos. En la referencia, la insignia API key de un endpoint significa que también se acepta una key de agente o de la organización; los endpoints sin ella son los de esta lista. Se dividen en cuatro familias:

  • Tus propias cosas: tus tareas, conteos, tableros recientes, bandeja, cursor de actividad, favoritos y vistas guardadas.
  • Quién puede ver: listas de miembros de proyecto (la lista de miembros de un tablero funciona con cualquier key). Cambiar miembros es una operación de administración (abajo).
  • A quién se notifica: participantes de tareas y suscripciones de seguimiento. Una key sin persona no tiene a nadie que responda por a quién se notifica.
  • Administración (tasks:admin): crear, editar, archivar y restaurar proyectos, tableros, estados de flujo y objetivos, reordenar estados, agregar y quitar adjuntos de proyectos y objetivos, agregar, cambiar y quitar miembros de tableros y proyectos, y vincular objetivos con proyectos. Una API key personal puede hacer todo esto.

Gestionar las etiquetas de la organización con la API de Plan (…/labels/) también requiere una persona.

Plan · Proyectos

Plan · Objetivos

Plan · Tableros

Plan · Tareas

Plan · Inicio y búsqueda

Qué pasa cuando Plan no está habilitado

Lo que recibes depende del motivo:

Situación Respuesta
El plan de tu organización permite Plan, pero todavía no está en la Beta 402 plan_upgrade_required en todos los endpoints de Plan, con cualquier credencial. Es lo esperado durante la Beta: escribe a [email protected]
Organización con plan gratuito, token de usuario del CLI 403 plan_upgrade_required, al iniciar sesión, antes de llegar a Plan
Organización con plan gratuito, API key de la organización 401 plan_free_api_keys_forbidden

GET /v1/plan/entitlements/ nunca responde 402: llámalo para saber si Plan está habilitado y, si no, por qué.

Errores de inicio de sesión

Vienen de la credencial misma, antes de que se aplique cualquier regla de Plan:

Estado Código Significado
401 credential_absent · credential_expired · credential_malformed Sin credencial, una vencida o una que no se puede leer
401 invalid_credentials La key o el token no existe
401 api_key_owner_inactive El dueño de la key fue desactivado
401 plan_free_api_keys_forbidden Las API keys no están disponibles en el plan gratuito
401 plan_missing_core_api_integrations El plan de la organización no incluye acceso a la API
403 plan_upgrade_required Inicio de sesión del CLI con plan gratuito que llega a un endpoint de pago
429 (limitado) Demasiadas solicitudes: espera los segundos que indica Retry-After

La lista completa de códigos de Plan está en las tablas de errores de la referencia y en Errores.