Desenvolva com o Trama

Token pessoal

Scripts e integrações do lado do servidor devem usar um token pessoal. Crie ou substitua o seu em ConfiguraçõesAPI e MCP. O mesmo token também funciona como Bearer token no servidor MCP, que faz a separação para você; a API REST só aceita os dois headers.

Quando X-Api-Key está presente, ela é a única credencial que a API considera: um par errado responde 401 mesmo que um header Authorization válido também seja enviado.

Login por e-mail (JWT)

O app web faz login com um código enviado por e-mail. Cada etapa é um POST /login: primeiro com o endereço, depois com o endereço e o código.

# 1. Peça um código (aqui, uma resposta 400 quer dizer que o e-mail foi enviado)
curl -X POST https://api.ontrama.com/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

# 2. Troque o código de 6 dígitos por um JWT (201: {"user": {…}, "token": "…"})
curl -X POST https://api.ontrama.com/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "otp": "123456"}'

# 3. Use o JWT
curl https://api.ontrama.com/me -H "Authorization: Bearer YOUR_JWT"

• Os códigos têm 6 dígitos, valem por 10 minutos e só funcionam uma vez. Só o código mais recente vale; cinco tentativas erradas o bloqueiam.
• O login é limitado a 30 requisições por IP e 10 por endereço a cada 15 minutos; acima disso, a resposta é 429 com Retry-After.
• POST /logout encerra todos os JWTs emitidos para a conta até então, em todos os dispositivos. Os tokens pessoais continuam funcionando.

OAuth 2.1

O Trama é um servidor de autorização OAuth 2.1, feito para clientes MCP: registro dinâmico de clientes (RFC 7591), metadados do servidor (RFC 8414), metadados do recurso protegido (RFC 9728) e o fluxo authorization code com PKCE (S256). Os clientes são públicos (token_endpoint_auth_method: none). Access tokens (lxt_at_…) duram 7 dias; refresh tokens (lxt_rt_…) são rotacionados a cada uso. Um cliente MCP faz tudo isso sozinho; o guia de MCP mostra o fluxo passo a passo.

São cinco scopes. Um cliente que não pede nenhum recebe todos, os dois de invoices só se você administra um workspace, e você os vê na página de consentimento.

Excluir marcos, etiquetas, checklists e links de PR, excluir comentários de tarefas, publicar documentos e excluir ou importar invoices continuam sendo feitos por pessoas, no app.

Você vê e revoga os apps que conectou em ConfiguraçõesApps conectados.

Chaves de tarefa

Toda tarefa recebe uma chave formada pelo prefixo do workspace e um número sequencial, como ACME-42. A chave não muda quando o cartão passa por outras colunas e quadros do workspace; mover a tarefa para outro workspace dá a ela uma chave nova. Citar uma chave em uma descrição ou em um comentário relaciona as duas tarefas, quando você pode editar o outro quadro.

• Ordem. Os cartões de uma coluna são ordenados por um sort_key fracionário. Cartões novos e movidos vão para o fim, a não ser que você passe insert_after_task_id.
• Prioridade. priority_none, priority_low, priority_medium, priority_high ou priority_urgent. Qualquer outro valor é um 422.
• Datas e marcos. start_at e due_at (o início não pode ser depois do prazo), e um milestone_id opcional de /boards/{board_id}/milestones, do mesmo quadro. Eles alimentam a visão de planejamento do quadro.

Subtarefas e relações

Uma tarefa pode ter uma tarefa-mãe (parent_id): do mesmo workspace, até 8 níveis de profundidade, sem ciclos e sem modelos. Crie subtarefas com POST …/tasks/{task_id}/sub_issues, enviando name, uma lista de names ou existing_task_id para adotar uma tarefa que já existe. Reordene-as com PUT …/tasks/{id}/reorder_sub_issues.

As relações são related, blocks, blocked_by e duplicate, criadas com POST …/tasks/{task_id}/relations. Quando uma tarefa que bloqueia outras é concluída, os links blocks dela viram related. A outra tarefa precisa estar em um quadro que você pode editar.

# Divida uma tarefa em subtarefas
curl https://api.ontrama.com/boards/41/tasks/7104/sub_issues \
  -H "X-Api-Key: $TRAMA_KEY" -H "X-Api-Secret: $TRAMA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"names": ["Draft the copy", "Review with legal"]}'

# Marque-a como bloqueada por outra tarefa (id ou chave)
curl https://api.ontrama.com/boards/41/tasks/7104/relations \
  -H "X-Api-Key: $TRAMA_KEY" -H "X-Api-Secret: $TRAMA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"related_task_id": "ACME-7", "relation_type": "blocked_by"}'

Modelos

Uma tarefa com is_template: true fica fora das colunas e aparece em templates no payload do quadro; ela não tem chave. Crie uma tarefa a partir dela com template_id em POST /boards/{board_id}/tasks: nome, descrição, prioridade, etiquetas e checklists são copiados (com os itens desmarcados). Responsáveis, datas, comentários e anexos não são.

Quem vê o quê

• Você vê um quadro se é membro dele, admin do workspace dele, membro do workspace quando o quadro é visível para o workspace, ou se simplesmente está logado quando o quadro é público (por link). Tudo o que está dentro de um quadro que você vê pode ser lido.
• Editar exige o papel de membro, admin ou dono no quadro, ou ser admin do workspace. Gerenciar o quadro (membros, compartilhamento, visibilidade, arquivar, excluir) exige admin ou dono.
• Um quadro que você não vê responde 404, não 403, para não revelar que ele existe.
• As invoices de um workspace (…/invoices) são só para os admins dele; qualquer outra pessoa recebe 404. Elas aceitam o seu token pessoal, um JWT ou um token OAuth com invoices.read / invoices.write.