Espaços de trabalho e organizações

Os espaços de trabalho são onde os membros de uma organização trabalham juntos: uma turma em uma escola, uma equipe em uma empresa. Uma requisição de API atua em um espaço de trabalho quando você envia o id dele no cabeçalho X-Nodaro-Workspace. Os endpoints de organização gerenciam tudo em volta: organizações, membros, convites, códigos de entrada, compartilhamento, orçamentos e uso.

As organizações são um recurso do Nodaro Cloud e são ativadas por instância. Onde não estão ativadas, os endpoints abaixo não existem e o cabeçalho é ignorado. As versões self-hosted não incluem organizações. Leia Espaços de trabalho para entender os conceitos.

Atuar em um espaço de trabalho

X-Nodaro-Workspace: 6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34

O cabeçalho faz duas coisas, e só essas duas: decide qual espaço de trabalho uma listagem retorna e onde fica o que você cria. Ele nunca concede acesso. Ler, atualizar, excluir ou executar algo que você indica pelo id segue o espaço de trabalho do próprio objeto. Um cabeçalho esquecido não pode esconder seu trabalho, e um cabeçalho forjado não pode acessar o trabalho de mais ninguém.

Sem o cabeçalho, você trabalha no seu espaço pessoal, como sempre acontece com uma conta sem organização.

curl -s https://app.nodaro.ai/v1/workflows \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "X-Nodaro-Workspace: 6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34"

// Every request of this client acts in the workspace:
const classClient = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
  workspaceId: '6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34',
})

// Or derive a second client from an existing one:
const classroom = client.withWorkspace(workspaceId)
await classroom.workflows.run(workflowId) // lands in the class
await client.workflows.run(workflowId)    // lands in the personal space

nodaro --workspace 6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34 workflows list   # this command only
export NODARO_WORKSPACE=6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34            # this shell or CI job
nodaro workspace use 6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34                # saved on the profile
nodaro workspace current                                                # which one applies, and why

client.withWorkspace retorna um cliente novo em vez de alterar o antigo, então duas operações executadas ao mesmo tempo nunca disputam o espaço de trabalho em que estão. Passe null para o espaço pessoal. Na CLI, cada uma das três formas tem prioridade sobre a que vem abaixo dela, e nodaro workspace use verifica o espaço de trabalho antes de salvá-lo.

Envie o cabeçalho apenas para um espaço de trabalho do qual você faz parte:

Estas requisições nunca recusam uma seleção desatualizada, para que ela nunca bloqueie o seu acesso: GET /v1/me, GET /v1/workspaces, a leitura e a aceitação de um convite e a entrada em um espaço de trabalho com um código. Nelas, um espaço de trabalho que você não pode mais selecionar é tratado como se você não tivesse enviado nenhum cabeçalho. GET /v1/me e GET /v1/workspaces informam quais espaços de trabalho você pode selecionar, então limpe uma seleção guardada em cache quando eles deixarem de listá-la.

Vincular um token a um espaço de trabalho

Um token de API pode ser vinculado a um espaço de trabalho. Ele passa a agir como se enviasse o cabeçalho em todas as requisições, e um cabeçalho explícito que indique outro espaço de trabalho responde 400 token_workspace_mismatch.

# Bind
curl -X PATCH https://app.nodaro.ai/v1/api-tokens/$TOKEN_ID \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId": "6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34"}'

# Unbind
curl -X PATCH https://app.nodaro.ai/v1/api-tokens/$TOKEN_ID \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId": null}'

O gerenciamento de tokens exige o JWT da sua sessão de login: um token de API ou um token OAuth recebe 403 forbidden. Você só pode vincular um token a um espaço de trabalho que poderia selecionar com o cabeçalho, e desvincular é sempre permitido. A listagem dos seus tokens retorna o vínculo como workspaceId.

Onde fica o que você cria

• Dentro de um espaço de trabalho, o que você cria fica no espaço de trabalho, nunca no seu espaço pessoal. Uma criação que não indica um projeto vai para o projeto do espaço de trabalho. Quando o espaço de trabalho ainda não tem projeto, a criação responde 409 workspace_has_no_default_project: indique um projeto, e ela funciona.
• Um projeto que você indica precisa pertencer ao espaço de trabalho em que você atua. Um projeto de outro espaço de trabalho, ou do seu espaço pessoal, responde 404 Project not found. É a mesma resposta de um projeto que não existe, então o cabeçalho não pode ser usado para descobrir o que existe.
• A criação de projetos pode ser limitada aos administradores. Nesse caso, os membros recebem 403 project_create_not_allowed.
• Uma organização pode desativar o espaço pessoal. Nesse caso, os membros só criam dentro de um espaço de trabalho, e uma criação sem o cabeçalho responde 403 personal_space_disabled. Contas sem organização nunca são afetadas.

Espaços de trabalho arquivados são somente leitura

Arquivar um espaço de trabalho mantém tudo o que há nele disponível para leitura e impede que novos trabalhos sejam adicionados. As listagens se comportam como antes. Toda criação, seja de um projeto, de um workflow, de uma importação ou de um sub-workflow, responde 409 workspace_archived, e o mesmo vale para mover trabalho para dentro do espaço de trabalho. Mover trabalho para fora continua permitido, porque resgatá-lo é o motivo para abrir um espaço de trabalho arquivado. Outras gravações nele, como compartilhar um workflow, respondem 403 workspace_archived. Compare pelo código, não pelo status.

Quem é você: GET /v1/me

GET /v1/me retorna o seu perfil. Em uma instância com organizações, ele também traz organizations, workspaces e lastWorkspaceId, e cada entrada vem com a sua própria função e o seu status. As entradas de organização incluem o vocabulary resolvido, como a palavra que a organização usa para um espaço de trabalho, para que um cliente nunca fixe no código “Class” ou “Team”. GET /v1/workspaces retorna sozinho a mesma lista de espaços de trabalho.

Diferencie os três estados dos campos de organização:

Endpoints de organização

Todos os endpoints exigem autenticação. Os corpos são JSON, as respostas são { "data": … }, as listas são { "data": [ … ], "nextCursor": … }, e os ids são UUIDs.

Organizações

• Aprovação. Uma nova organização normalmente começa como pending e passa a active quando a plataforma a aprova. Enquanto ela aguarda, o proprietário a vê, mais ninguém a vê, e nada nela pode mudar. Avise quem a criou; caso contrário, a espera parece uma falha.
• Escolas exigem os termos. Criar uma escola exige acceptTerms: true, com o qual o proprietário confirma ter autoridade para matricular alunos. Sem isso, a criação responde 400 terms_required.
• Os slugs têm de 1 a 50 letras minúsculas, dígitos e hifens. Um slug que você envia precisa estar livre (409 name_taken). Sem slug, ele é derivado do nome: “Sunrise School” vira sunrise-school, depois sunrise-school-2.
• A criação de organizações é limitada a algumas por hora para cada usuário.

Membros

Espaços de trabalho

Membros do espaço de trabalho

Os proprietários e os administradores da organização são administradores de todos os espaços de trabalho da organização sem aparecer na lista. Adicionar um deles explicitamente a um espaço de trabalho dá a essa pessoa a função explícita atribuída, no lugar da implícita. É assim que um administrador da organização pode ser um membro comum de uma turma.

Convites

Um convite indica um único endereço de e-mail. O link dele leva um token que só existe no e-mail, e a pessoa convidada vê para o que foi convidada antes de fazer login.

• Cada endereço recebe sua própria linha. status é sent, link_only ou failed, e link aparece sempre que o endereço não recebeu e-mail. Uma instalação sem provedor de e-mail retorna todos os endereços como link_only. Mostre esses links: o convite existe de qualquer forma, e sem o link ninguém consegue chegar até ele.
• Os convites expiram depois de 14 dias, e uma organização pode enviar 500 por dia (429 bulk_invite_cap_exceeded).
• Convidar um endereço de novo passa o convite em aberto para um token novo, em vez de criar um segundo convite.
• Convidar alguém que já é membro consome o convite, mas não muda a função da pessoa nem remove uma suspensão.

Códigos de entrada

Um código de entrada tem oito caracteres, curto o bastante para ser lido em voz alta em uma sala. Ele admite um membro comum em um espaço de trabalho, nunca remove uma suspensão e respeita os domínios de e-mail permitidos pela organização.

Compartilhar um workflow

Uma concessão de acesso dá a uma pessoa acesso a um workflow. Ela só pode adicionar acesso, nunca removê-lo.

• Quem pode compartilhar: o criador; um administrador do espaço de trabalho, onde os administradores podem editar o trabalho dos membros; e qualquer pessoa que possa editar o workflow, onde o espaço de trabalho permite que colaboradores convidem.
• Adicionar por e-mail encontra o endereço de qualquer conta, seja qual for a organização dela. 404 significa que não existe conta, e nada além disso é revelado.
• Alguém de fora do espaço de trabalho fica limitado a visualizar, mesmo com uma concessão de editor. Executar exige ser membro ativo, então um colaborador de fora nunca pode gastar os créditos do espaço de trabalho.
• Você não pode dar uma concessão ao criador do workflow nem a si mesmo (400). Uma concessão vale na hora, sem etapa de aceitação.
• canChangeVisibility, canShare e canRun são três regras separadas. Nunca deduza uma a partir de outra.

Um workflow que você não consegue acessar de forma alguma responde 404, igual a um que não existe. Só quando você já consegue vê-lo e precisa de mais acesso é que a resposta passa a ser 403. Executar um workflow que pertence a um espaço de trabalho exige acesso de edição e ser membro ativo.

Log de auditoria

O log de auditoria continua disponível para leitura enquanto a organização está suspensa. action é uma lista aberta que cresce com o produto: mostre as ações que você conhece e, para as demais, use o valor bruto.

Funções e configurações

As configurações funcionam em camadas: a configuração de um espaço de trabalho prevalece sobre a da organização, que prevalece sobre o padrão do tipo de organização. Uma chave não definida passa para a camada seguinte, e false é um valor real.

Só a organização tem também allowed_email_domains, como ["school.example"], e vocabulary_overrides, como { "workspace": "Cohort" }. As duas chaves são substituídas por inteiro quando atualizadas.

Quando você define a sua própria palavra para um espaço de trabalho, defina também workspace_gender em vocabulary_overrides como "m" se a palavra for gramaticalmente masculina, por exemplo { "workspace": "Grupo", "workspace_gender": "m" }. Assim, as frases em hebraico e em português do Brasil que citam o espaço de trabalho concordam com a palavra. Sem "m", elas tratam a palavra como feminina. Essa configuração só existe na API.

Uma escola começa assim: administradores editam, workflows privados, membros veem o trabalho compartilhado, membros não podem criar projetos, limites ativados, espaço pessoal ativado, administradores de espaço de trabalho podem convidar e colaboradores não podem. Uma equipe começa assim: administradores veem, workflows visíveis para o espaço de trabalho, membros editam o trabalho compartilhado, membros podem criar projetos, limites desativados, espaço pessoal ativado e as duas configurações de convite ativadas.

Orçamentos e uso

Uma organização paga pelo trabalho dos membros em três etapas, cada uma mais restrita que a anterior:

1. O fundo comum. A organização compra pacotes de créditos pré-pagos para um único fundo comum de toda a organização, pelo próprio checkout.
2. Alocações. O proprietário transfere créditos do fundo comum para o orçamento de um espaço de trabalho. O fundo comum diminui exatamente o que o espaço de trabalho ganha. Os créditos podem voltar para o fundo comum, mas a alocação do espaço de trabalho não pode ficar abaixo do que ele já reservou ou gastou.
3. Limites por membro. Dentro de um espaço de trabalho, um administrador pode limitar quanto um membro pode gastar. Os limites só se aplicam onde as configurações do espaço de trabalho os ativam, e nunca a um administrador da organização que trabalhe no espaço de trabalho.

O trabalho feito dentro de um espaço de trabalho é pago pelo espaço de trabalho, e os créditos do próprio membro não são usados. Em cada nível, a margem disponível é o valor alocado menos o reservado menos o gasto. Uma execução que ultrapassaria essa margem é recusada com 402 budget_exceeded ou 402 member_cap_exceeded antes de começar.

Reembolsos e contestações de pagamento retiram créditos do fundo comum da organização na proporção correspondente, nunca abaixo de zero. Para excluir uma organização, é preciso recolher antes todas as alocações dos espaços de trabalho.

As automações gastam os créditos do espaço de trabalho. A URL de um nó Gatilho de webhook (Webhook Trigger) é uma credencial do tipo bearer: quem a tiver pode iniciar uma execução. A execução de um workflow de um espaço de trabalho é paga por esse espaço de trabalho. Toda execução automática, vinda de um webhook, de um agendamento ou do Telegram, verifica primeiro se quem criou o gatilho ainda pode executar o workflow. Quando essa pessoa não pode mais, a automação para, e o histórico de execuções mostra uma entrada com falha e o código run_requires_authenticated_member.

Relatórios de uso

As duas rotas de uso respondem quem gastou quanto e em quê, em um intervalo de datas:

• Cada linha tem três valores de créditos. credits é o que as execuções custaram até agora: o valor liquidado das execuções terminadas e a reserva retida das execuções em andamento. settledCredits e inFlightCredits dividem essa soma.
• Uma execução cobrada por consumo que custou mais do que o espaço de trabalho ainda tinha é cobrada até a margem disponível, e a plataforma absorve o restante. Os totais informam isso como platformAbsorbedCredits, e settledCredits menos platformAbsorbedCredits é o que chegou ao orçamento. Um acréscimo (markup) de app aprovado que o orçamento não conseguiu cobrir também é absorvido e informado à parte como appMarkupAbsorbedCredits.
• Um relatório com mais de 5.000 grupos retorna truncated: true. Só as linhas agrupadas são cortadas: os totais cobrem o intervalo inteiro.
• Um membro comum vê só as próprias execuções, e o agrupamento por membro é recusado para ele. Um administrador do espaço de trabalho vê todo mundo e pode filtrar por userId. O relatório da organização é para os proprietários e os administradores da organização.
• As exportações CSV são UTF-8, RFC 4180, com finais de linha CRLF e sem marca de ordem de bytes (BOM). Uma célula que começa com =, +, - ou @ recebe um apóstrofo no início, para que uma planilha não possa executá-la. As exportações são limitadas a 10 por minuto para cada usuário e ficam registradas no log de auditoria.
• Quando um membro exclui a própria conta, o histórico de execuções dele vai junto, e o relatório mostra uma lacuna. Os workflows e os projetos dele ficam com o espaço de trabalho.

Uma instância sem relatórios de uso responde 404, e responde 503 billing_unavailable enquanto os relatórios ainda não estão disponíveis.

Erros

Pelo SDK, pela CLI e pelo MCP

• SDK: client.organizations e client.workspaces cobrem esses endpoints, incluindo usage, usageRows e usageCsv para os relatórios. client.me() traz os campos de organização.
• CLI: nodaro org e nodaro workspace, por exemplo nodaro org invite <orgId> --email ada@school.example --workspace <id> e nodaro org usage <orgId> --from 2026-09-01 --to 2026-09-30 --group-by member --csv > september.csv. O comando de convite imprime uma linha por endereço, com o link de cada endereço que não recebeu e-mail.
• MCP: as ferramentas list_workspaces e select_workspace. A seleção é lembrada entre as sessões e verificada de novo em cada uma. Um app OAuth que usa essas ferramentas precisa dos escopos workspaces:read e workspaces:write.

Leia A CLI e O SDK para ver as listas completas de comandos e de métodos.