Autenticação e scopes do Plan

A API do Plan aceita três credenciais. Elas se comportam de forma diferente, então escolha a que corresponde a quem está agindo. As regras gerais de toda a API do Dailybot estão em Autenticação e Autenticação da CLI; esta página cobre o que é específico do Plan.

Três credenciais

Credencial	Como enviar	Age como	Use para
Sessão iniciada	Authorization: Bearer <token> (o app web, ou dailybot login para a CLI)	Você, com o seu papel	O app web do Dailybot, e scripts e agentes que trabalham em nome de uma pessoa
API key pessoal	X-API-KEY: <key>	A pessoa que a criou, para si mesma	Scripts, CI e agentes que devem ser essa pessoa
Key de agente ou da organização	X-API-KEY: <key>	Um ator de sistema: sem uma pessoa por trás	Integrações servidor a servidor que leem ou escrevem trabalho visível para a organização

Sessão iniciada: age como você

Uma sessão iniciada carrega a sua identidade e o seu papel na organização. dailybot login obtém uma com um código de uso único enviado por e-mail; o mesmo fluxo está disponível por HTTP (veja o início rápido). Um token de login só viaja para o host da API que o emitiu.

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

API key pessoal: age como sua pessoa

Uma API key pessoal é criada por uma pessoa para si mesma. No Plan ela responde exatamente como essa pessoa no app web:

• Ela vê o que a pessoa vê, incluindo os quadros privados dos quais participa. me é a pessoa, e cada escrita é registrada como a pessoa.
• Ela pode fazer tudo o que a pessoa pode fazer em cada endpoint do Plan: todas as leituras e todas as escritas de tarefas, e todas as escritas de estrutura e de associações: projetos, quadros, colunas, metas, marcos, membros (por usuário ou time), participantes, silenciar, visualizações salvas e anexos.
• Não há pré-requisito de administrador da organização nem scope a solicitar: todo membro não convidado pode, então a key dele também.
• Uma key cuja linha traz scopes tasks:* explícitos tem um teto escolhido pela pessoa: tasks:write cobre também as operações de administração, e tasks:read mantém a key somente leitura. Uma key só com scopes fora do Plan não tem acesso ao Plan.

curl -sS "https://api.dailybot.com/v1/plan/me/tasks/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY"

Key de agente ou da organização: um ator de sistema

Uma key sem uma pessoa por trás nunca age como uma pessoa:

• Ela vê somente quadros visíveis para a organização, nunca quadros restritos a membros.
• Ela não tem me: ?owner=me responde 400 actor_required.
• Endpoints que exigem uma pessoa ou um administrador (listados abaixo) respondem 403 insufficient_scope.
• Ela precisa ter scopes do Plan próprios (tasks:read e tasks:write).
• Ela age como uma pessoa específica somente quando a requisição também traz um exchange token (X-EXCHANGE-TOKEN), como descrito em Autenticação.
• Ela não pode nomear um agente em uma escrita: enviar um nome de agente com uma key de agente é 400 invalid_agent_attribution.

curl -sS "https://api.dailybot.com/v1/plan/boards/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY"

Keys de agente e da organização precisam ter scopes do Plan habilitados. Uma key nova não tem nenhum. Durante o Beta, escreva para [email protected] para habilitá-los.

Convidados são limitados pelo papel com uma key ou uma sessão igualmente: 403 guest_not_allowed, antes de verificar qualquer outra coisa. Uma key expirada é 401 credential_expired; uma key revogada ou um dono desativado também é 401 (veja os erros de login).

Scopes

Scope	Concede
tasks:read	Todas as leituras
tasks:write	Escritas de linha: tarefas, comentários, etiquetas, relações, participantes. Na linha de uma key cobre também as operações de administração abaixo
tasks:admin	Escritas de contêineres: projetos, quadros, estados, associações, metas. Todo membro não convidado o tem

Cada endpoint da referência informa o seu scope. Como cada credencial os obtém:

Credencial	Scopes
Sessão iniciada, membro não convidado	tasks:read, tasks:write, tasks:admin
API key pessoal	Tudo o que a sua pessoa pode fazer, sem conceder nada. Se a linha da key lista scopes do Plan explícitos, eles são um teto
Key de agente ou da organização	Somente os scopes concedidos à key (tasks:read, tasks:write); é recusada nos endpoints que exigem uma pessoa
Convidado, com qualquer credencial	Nenhum: recusado com 403 guest_not_allowed antes do entitlement

Uma chamada sem o scope de que precisa responde 403 insufficient_scope.

A privacidade é a associação (convite), não o papel da organização. Contêineres de toda a organização são um espaço compartilhado. Um projeto, quadro ou tarefa members responde 404 not found a quem não tem um grant, em leituras, listas, busca, comentários, anexos e atividade igualmente. Trate como não visível, nunca como «não permitido». Um quadro dentro de um projeto members segue a associação do projeto, e os quadros expõem effective_visibility (org ou members) para você distinguir. Convide uma pessoa ou um time com escritas de associação para compartilhar; o último grant em um contêiner privado é 409 last_grant_cannot_be_removed. Não há papéis por projeto como lead ou viewer: associação é apenas um grant.

Supervisão. Administradores da organização e managers de todos os times podem ver todos os projetos. Um quadro members ainda precisa de um grant explícito.

Convidados são recusados antes de qualquer outra verificação, então um convidado nunca descobre se a organização tem o Plan habilitado nem quão perto está dos limites do plano.

Endpoints que exigem uma pessoa

Alguns endpoints precisam de uma pessoa por trás da requisição, então uma key de agente ou da organização é recusada com 403 insufficient_scope. Uma sessão iniciada e uma API key pessoal funcionam em todos. Na referência, o selo API key de um endpoint significa que uma key de agente ou da organização também é aceita; os endpoints sem ele são os desta lista. Eles se dividem em quatro famílias:

• As suas próprias coisas: suas tarefas, contagens, quadros recentes, caixa de entrada, cursor de atividade, favoritos e visualizações salvas.
• Quem pode ver: listas de membros de projeto (a lista de membros de um quadro funciona com qualquer key). Alterar membros é uma operação de administração (abaixo).
• Quem é notificado: participantes de tarefas e assinaturas de acompanhamento. Uma key sem pessoa não tem ninguém para responder por quem é notificado.
• Administração (tasks:admin): criar, editar, arquivar e restaurar projetos, quadros, estados de fluxo e metas, reordenar estados, adicionar e remover anexos de projetos e metas, adicionar, alterar e remover membros de quadros e projetos, e vincular metas a projetos. Uma API key pessoal pode fazer tudo isso.

Gerenciar as etiquetas da organização pela API do Plan (…/labels/) também exige uma pessoa.

Plan · Projetos

• POST /v1/plan/projects/: Criar um projeto
• PATCH /v1/plan/projects/{project_id}/: Atualizar um projeto
• POST /v1/plan/projects/{project_id}/archive/: Arquivar um projeto, em cascata para os seus quadros e as tarefas deles
• POST /v1/plan/projects/{project_id}/restore/: Restaurar um projeto arquivado
• GET /v1/plan/projects/{project_id}/views/: As visualizações salvas desta pessoa dentro de um projeto
• PUT /v1/plan/projects/{project_id}/views/: Substituir as visualizações salvas desta pessoa em um projeto
• GET /v1/plan/projects/{project_id}/members/: Membros de um projeto
• POST /v1/plan/projects/{project_id}/members/: Convidar alguém, ou uma equipe inteira, para um projeto
• DELETE /v1/plan/projects/{project_id}/members/{user_id}/: Remover alguém de um projeto
• PATCH /v1/plan/projects/{project_id}/members/{user_id}/: Inspecionar uma concessão de associação a um projeto (o papel é somente leitura)
• POST /v1/plan/projects/{project_id}/attachments/: Enviar um anexo para um projeto
• DELETE /v1/plan/projects/{project_id}/attachments/{attachment_id}/: Remover um anexo de um projeto

Plan · Metas

• POST /v1/plan/goals/: Criar uma meta
• PATCH /v1/plan/goals/{goal_id}/: Atualizar uma meta ou declarar seu status
• POST /v1/plan/goals/{goal_id}/archive/: Arquivar uma meta. Os projetos permanecem, sem meta
• POST /v1/plan/goals/{goal_id}/restore/: Trazer de volta uma meta arquivada
• POST /v1/plan/goals/{goal_id}/projects/: Vincular um projeto a uma meta (a partir da página da meta)
• DELETE /v1/plan/goals/{goal_id}/projects/{project_id}/: Desvincular um projeto de uma meta
• POST /v1/plan/goals/{goal_id}/attachments/: Enviar um anexo para uma meta
• DELETE /v1/plan/goals/{goal_id}/attachments/{attachment_id}/: Remover um anexo de uma meta

Plan · Quadros

• POST /v1/plan/boards/: Criar um quadro e gerar seus cinco estados padrão
• PATCH /v1/plan/boards/{board_id}/: Atualizar um quadro, incluindo renomear sua chave
• POST /v1/plan/boards/{board_id}/archive/: Arquivar um quadro, em cascata para as suas tarefas
• POST /v1/plan/boards/{board_id}/restore/: Restaurar um quadro arquivado
• POST /v1/plan/boards/{board_id}/visit/: Registrar que quem chama abriu um quadro (recent_boards do HomePulse)
• POST /v1/plan/boards/{board_id}/states/: Adicionar um estado a um quadro
• PATCH /v1/plan/boards/{board_id}/states/{state_id}/: Renomear, mudar a cor ou reordenar um estado
• POST /v1/plan/boards/{board_id}/states/{state_id}/archive/: Aposentar uma coluna
• POST /v1/plan/boards/{board_id}/states/{state_id}/restore/: Restaurar uma coluna retirada
• POST /v1/plan/boards/{board_id}/states/reorder/: Reordenar todas as colunas ativas de um quadro em uma chamada
• GET /v1/plan/boards/{board_id}/views/: As visualizações salvas de quem chama para este quadro
• PUT /v1/plan/boards/{board_id}/views/: Substituir as visualizações salvas de quem chama para este quadro
• GET /v1/plan/boards/{board_id}/mentionables/: Pesquisar pessoas que podem ser mencionadas em um quadro
• POST /v1/plan/boards/{board_id}/members/: Adicionar um membro a um quadro
• DELETE /v1/plan/boards/{board_id}/members/{user_id}/: Remover um membro de um quadro
• PATCH /v1/plan/boards/{board_id}/members/{user_id}/: Inspecionar uma concessão de associação a um quadro (o papel é somente leitura)
• GET /v1/plan/boards/{board_id}/labels/: Listar etiquetas da organização (verificação de acesso ao quadro)
• POST /v1/plan/boards/{board_id}/labels/: Criar uma etiqueta da organização
• GET /v1/plan/views/{view_id}/: Uma visualização salva por uuid
• PATCH /v1/plan/views/{view_id}/: Editar uma visualização salva
• DELETE /v1/plan/views/{view_id}/: Excluir uma visualização salva

Plan · Tarefas

• POST /v1/plan/tasks/{task_id}/subscription/: Inscrever-se nas notificações da tarefa (papel de observador)
• DELETE /v1/plan/tasks/{task_id}/subscription/: Remover uma inscrição de observador
• GET /v1/plan/tasks/{task_id}/participants/: Quem está neste card
• POST /v1/plan/tasks/{task_id}/participants/: Colocar alguém neste card
• DELETE /v1/plan/tasks/{task_id}/participants/{user_uuid}/: Tirar alguém deste card

Plan · Início e busca

• GET /v1/plan/me/tasks/: As tarefas do usuário que faz a chamada
• GET /v1/plan/me/tasks/counts/: Contagens das abas de tarefas pessoais
• GET /v1/plan/me/recents/: Quadros visitados recentemente por quem chama
• GET /v1/plan/inbox/: Eventos de tarefas relevantes para notificação de quem chama
• POST /v1/plan/inbox/read-all/: Marcar todos os itens da caixa de entrada como lidos
• POST /v1/plan/inbox/{item_uuid}/read/: Alcançar até uma linha da caixa de entrada
• GET /v1/plan/inbox/unread-count/: Contagem de não lidos da caixa de entrada de quem chama
• GET /v1/plan/me/activity-cursor/: Ler o cursor de leitura de atividade de quem chama
• PUT /v1/plan/me/activity-cursor/: Marcar a atividade como lida até um timestamp
• GET /v1/plan/labels/: Listar etiquetas da organização
• POST /v1/plan/labels/: Criar uma etiqueta da organização
• PATCH /v1/plan/labels/{label_id}/: Atualizar uma etiqueta da organização
• DELETE /v1/plan/labels/{label_id}/: Excluir uma etiqueta da organização
• GET /v1/plan/me/favorites/: Seus quadros e visualizações salvas fixados
• POST /v1/plan/me/favorites/: Fixar um quadro ou uma visualização salva
• PATCH /v1/plan/me/favorites/{favorite_id}/: Mover um pin dentro da sua lista
• DELETE /v1/plan/me/favorites/{favorite_id}/: Desafixar

O que acontece quando o Plan não está habilitado

O que você recebe depende do motivo:

Situação	Resposta
O plano da sua organização permite o Plan, mas ela ainda não está na Beta	402 plan_upgrade_required em todos os endpoints do Plan, com qualquer credencial. Isso é esperado durante a Beta: escreva para [email protected]
Organização no plano gratuito, token de usuário da CLI	403 plan_upgrade_required, no login, antes de chegar ao Plan
Organização no plano gratuito, API key da organização	401 plan_free_api_keys_forbidden

GET /v1/plan/entitlements/ nunca responde 402: chame-o para saber se o Plan está habilitado e, se não estiver, por quê.

Erros de login

Eles vêm da própria credencial, antes de qualquer regra do Plan ser aplicada:

Status	Código	Significado
401	credential_absent · credential_expired · credential_malformed	Nenhuma credencial, uma expirada ou uma que não pode ser lida
401	invalid_credentials	A key ou o token não existe
401	api_key_owner_inactive	O dono da key foi desativado
401	plan_free_api_keys_forbidden	API keys não estão disponíveis no plano gratuito
401	plan_missing_core_api_integrations	O plano da organização não inclui acesso à API
403	plan_upgrade_required	Login da CLI no plano gratuito chegando a um endpoint pago
429	(limitado)	Requisições demais: aguarde os segundos indicados em Retry-After

A lista completa de códigos do Plan está nas tabelas de erros da referência e em Erros.