Autenticação
Autentique chamadas à API do Nodaro com token de API pessoal, token de app OAuth ou JWT de sessão, e crie, limite, vincule e revogue os seus tokens de API.
Toda requisição à API do Nodaro se autentica com um token Bearer no cabeçalho Authorization. Use um token de API pessoal (ndr_…) quando o seu próprio servidor chama o Nodaro para a sua conta. Use um token de acesso OAuth (ndr_app_…) quando o seu produto age em nome de outros usuários do Nodaro, e o JWT da sua sessão em uma instalação auto-hospedada da Community Edition.
Authorization: Bearer ndr_4f1c…Qual credencial usar
| O seu caso | Use | Formato do token |
|---|---|---|
| Automatizar a sua própria conta do Nodaro a partir de um servidor, de uma tarefa do cron ou de um pipeline de CI | Token de API pessoal | ndr_ seguido de 64 caracteres hexadecimais |
| Criar um produto que executa workflows nas contas do Nodaro de outros usuários | Token de acesso OAuth | ndr_app_ seguido de 64 caracteres hexadecimais |
| Rodar a Community Edition auto-hospedada para você mesmo | O JWT da sua sessão | Um JWT, começando com eyJ |
Um teste rápido: se o seu servidor precisa de um único conjunto de credenciais e de nenhuma tela de consentimento, use um token de API. Se muitos clientes precisam, cada um, dar ao seu app acesso à própria conta, use OAuth.
Os tokens de API estão disponíveis no Nodaro Cloud e na Business edition. Na Community Edition, chame os mesmos endpoints com o token de acesso da sua sessão com login. Veja Edições.
Criar um token de API
Abrir a página Tokens de API
Faça login no Nodaro e abra Configurações › Tokens de API. No Nodaro Cloud, a página fica em https://app.nodaro.ai/settings/api.
Criar o token
Clique em Criar token. Na caixa de diálogo Criar token de API, digite um Nome para o seu controle, como prod-scheduler, e um Limite de taxa (requisições/min) de 1 a 120. O padrão é 30 requisições por minuto.
Copiar o token agora
Clique em Criar e copie o token para o seu cofre de segredos. O token só aparece uma vez. O Nodaro guarda apenas um hash SHA-256 dele, então um token perdido não pode ser recuperado: em vez disso, crie um novo.
A página lista cada token com o nome, o prefixo, o limite de taxa, a data do último uso e a data de criação. O botão de alternância ao lado de um token o ativa ou desativa, e o botão de lixeira o exclui.
Regras dos tokens de API
- Até 10 tokens por conta, ativos ou não. Um token desativado continua contando, então exclua-o para liberar a vaga. Um 11º token é recusado com
400 limit_reached. - Sem expiração e sem limite de gastos. Um token funciona até você desativá-lo ou excluí-lo. Excluir um token o revoga imediatamente.
- O token age como você. Toda chamada feita com ele é executada como a sua conta e gasta os seus créditos.
- Ele não é verificado de novo no seu provedor de login. Um token criado antes de a sua conta ser removida de um provedor de identidade continua funcionando até você revogá-lo. Trate todo token como uma credencial permanente.
Limitar um token a alguns workflows
Um token pode ser limitado a uma lista de workflows, o escopo de workflows dele. Um token criado na página Tokens de API não tem escopo: ele pode executar todos os workflows que são seus. Um token sem workflowIds é o token de acesso total da conta.
Defina o escopo com o campo workflowIds, com até 50 workflows, ao criar ou atualizar um token pelos endpoints abaixo. Uma mudança no escopo vale em até um minuto. Só os workflows do seu espaço pessoal podem entrar na lista: um workflow que fica em um espaço de trabalho responde 400 invalid_workflow.
Um token com escopo serve para executar os workflows dele. Ele pode executá-los, lê-los com as entradas deles e acompanhar as execuções deles, e nada mais:
GET /v1/api/workflows,GET /v1/workflowseGET /v1/projects/:projectId/workflowslistam só esses workflows.GET /v1/executionslista só as execuções deles.GET /v1/api/schema,POST /v1/api/run,GET /v1/workflows/:id,GET /v1/workflows/:id/interface,POST /v1/workflows/:id/run,POST /v1/workflows/:id/render-final/estimateeGET /v1/workflows/:id/executionsrespondem só para esses workflows.GET /v1/api/status/:execId,GET /v1/api/result/:execIdeGET /v1/workflow-executions/:id, com as rotas/streame/cancel, respondem só para execuções desses workflows. Uma execução que não é sua responde404.- As rotas que não pedem login, como a galeria pública e os catálogos de modelos e de nós, respondem como respondem sem token.
Qualquer outra requisição responde 403 forbidden, com a mensagem “This API key is limited to specific workflows, and this request is outside them. Use a key without a workflow limit for anything else.” Isso inclui outro workflow ou as execuções dele, editar ou excluir um workflow, as rotas de geração direta, uploads, tarefas, apps publicados, MCP e o uso como credencial de retransmissão. A requisição é recusada antes de qualquer execução, então nada é reservado nem cobrado.
Gerenciar tokens por código
| Método | Caminho | O que faz |
|---|---|---|
POST | /v1/api-tokens | Cria um token. Corpo { name, workflowIds, rateLimit }. A resposta é a única vez em que o token completo aparece. |
GET | /v1/api-tokens | Lista os seus tokens com as configurações e a vinculação a um espaço de trabalho (workspaceId). O token em si nunca é retornado. |
PATCH | /v1/api-tokens/:id | Muda o nome, o escopo de workflows, o limite de taxa, o indicador de ativo ou a vinculação a um espaço de trabalho. |
DELETE | /v1/api-tokens/:id | Exclui o token. Ele para de funcionar na hora. |
Essas quatro rotas só funcionam a partir de uma sessão com login, então envie o JWT da sua sessão, não um token de API. Um token de API pessoal ou um token OAuth é recusado com 403 forbidden e a mensagem “API token management is only available from a logged-in session”. Em uma instalação da Community Edition, as rotas de criação e de listagem respondem 403 edition_required com required_edition: "business".
Para vincular um token a um espaço de trabalho, veja Vincular um token a um espaço de trabalho.
Enviar o token
GET /v1/me retorna a conta por trás de qualquer token válido, por isso é o jeito mais rápido de verificar um token. Um token ausente, inválido ou revogado responde 401 unauthorized.
curl https://app.nodaro.ai/v1/me \
-H "Authorization: Bearer $NODARO_API_KEY"{
"data": {
"id": "5bf0d884-47b1-468e-a7b2-2433f957b267",
"email": "ada@example.com",
"displayName": "Ada",
"avatarUrl": null,
"tier": "pro",
"isAdmin": false
}
}import { createClient, StaticTokenAuth } from '@nodaro/sdk'
const client = createClient({
baseUrl: 'https://app.nodaro.ai',
auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})
const me = await client.me()
console.log(me.email, me.tier)nodaro auth login --token "$NODARO_API_KEY"
nodaro auth statusEm uma conta que pertence a uma organização, a mesma resposta também traz as organizações e os espaços de trabalho dos quais a conta faz parte. Veja Espaços de trabalho e organizações.
O SDK obtém o token de um provedor de autenticação, então você escolhe como o token é encontrado:
| Provedor | Use para |
|---|---|
StaticTokenAuth | Um token fixo em um servidor: um token de API ou um token de acesso OAuth. |
supabaseAuth(supabase) | Um app de navegador que compartilha o login da instalação do Nodaro. O token da sessão é lido a cada requisição, então a renovação é automática. |
CallbackAuth | A sua própria lógica, por exemplo um armazenamento de sessões que renova tokens. O callback pode retornar null para não enviar cabeçalho. |
A CLI salva o token em ~/.config/nodaro/config.json com o modo de arquivo 0600. Adicione --profile e --base-url para manter um segundo login para uma instalação auto-hospedada, por exemplo nodaro auth login --profile local --base-url http://localhost:3000.
Tokens de acesso OAuth
Use OAuth quando cada um dos seus usuários conecta a própria conta do Nodaro ao seu produto. O seu servidor troca um código de autorização por um token de acesso que começa com ndr_app_. O token dura 90 dias, e não há tokens de atualização: depois que ele expirar, faça o usuário passar de novo pela tela de consentimento.
Um token OAuth só tem os escopos que o usuário concedeu. Uma rota que precisa de um escopo que o token não tem responde 403 insufficient_scope, e o erro indica o escopo em missingScope. Os escopos de que a maioria das integrações com a API precisa:
| Escopo | Concede |
|---|---|
workflows:read | Ler os workflows do usuário: GET /v1/workflows, GET /v1/workflows/:id, a exportação e a lista por projeto. Também os apps publicados do próprio usuário, as análises e os ganhos deles. |
workflows:write | Criar, mudar, importar e excluir workflows. Também publicar, mudar, excluir e restaurar apps. |
workflows:execute | Executar workflows com POST /v1/workflows/:id/run. Também executar apps publicados e componentes, e tentar de novo, renderizar ou excluir execuções de apps. |
jobs:read | Ler o status e os resultados das tarefas, inclusive a consulta periódica em lote, e ler execuções de apps. |
Os tokens de API pessoais e os JWTs de sessão não têm escopos: eles agem como a sua própria conta. Leia o fluxo completo, todos os escopos e a tela de consentimento em Apps OAuth, e os escopos das rotas de apps em Gerenciar apps publicados.
Rotas que precisam de uma sessão com login
Algumas rotas existem para o app web do Nodaro e recusam tanto tokens de API quanto tokens OAuth:
| Rota | Resposta a um token |
|---|---|
/v1/api-tokens (gerenciamento de tokens) | 403 forbidden |
/v1/billing/* (finalização de compra, recargas, recarga automática, histórico de compras) | 403 forbidden |
| Escritas em predefinições de nós | 403 forbidden |
/v1/copilot/* (o Workflow Copilot) | 403 in_app_only |
/v1/http-credentials (chaves armazenadas para a Saída de webhook) | 403 in_app_only |
Para montar workflows por código, use os endpoints de workflow, o SDK ou o servidor MCP.
Identificar o seu cliente
Envie um cabeçalho X-Nodaro-Client, e o Nodaro o registra como a origem de cada tarefa que a requisição criar:
X-Nodaro-Client: sdk/1.10.0Só três formas são reconhecidas: sdk/<version>, cli/<version> e extension/<name>. Qualquer outro valor é ignorado, porque o cabeçalho não é autenticado. O @nodaro/sdk e o @nodaro/cli enviam esse cabeçalho por você, então você só precisa dele quando chama a API REST diretamente. Omiti-lo não é problema: essas tarefas ficam registradas como chamadas genéricas à API.
Quem chama a partir de um navegador não deve enviar o cabeçalho. O cabeçalho Origin do navegador já indica o site, e o Nodaro dá preferência a ele. O SDK omite o cabeçalho automaticamente quando roda em um navegador.
Manter os tokens no seu servidor
Um token no código do navegador pode ser lido por qualquer pessoa com as ferramentas de desenvolvedor, e ele pode gastar os seus créditos. Mantenha o token em uma rota de servidor, em uma função de borda ou no cofre de segredos da sua plataforma, e deixe o navegador falar só com o seu servidor:
Browser -> your server (holds NODARO_API_KEY) -> Nodaro APINo Next.js, por exemplo, leia o token em um route handler a partir de uma variável de ambiente sem o prefixo NEXT_PUBLIC_. Se você chamar o Nodaro a partir de um navegador com um token OAuth, adicione a origem do seu site às origens permitidas do app de desenvolvedor.
Conectar uma instalação auto-hospedada com um token
Um token de API pessoal sem escopo de workflows também é o jeito mais simples de executar as gerações de uma instalação auto-hospedada no Nodaro Cloud. Na instalação auto-hospedada, defina NODARO_CLOUD_URL com o endereço do Nodaro Cloud e NODARO_API_KEY com o seu token. Assim, toda geração é executada no Nodaro Cloud e cobrada da conta do token, sem conexão OAuth. Veja Conectar ao Nodaro Cloud.
Implantações com uma única conta de cobrança
Algumas implantações têm uma única conta de cobrança que paga por todos os usuários. Nessas implantações:
- Só a conta de cobrança pode criar um token. Qualquer outra pessoa recebe
403 api_tokens_payer_only, e os tokens existentes continuam podendo ser listados e revogados pelos donos. - O card Tokens de API não aparece em Configurações. A conta de cobrança abre
/settings/apidiretamente. - Toda chamada feita com um token é paga com o saldo compartilhado da implantação.
- Um token não pode ler esse saldo compartilhado. As leituras de saldo feitas com o token da conta de cobrança respondem
403 payer_balance_jwt_only, e as rotas de cobrança da implantação respondem403 payer_required.
Erros
| Status | Código | Significado |
|---|---|---|
| 400 | limit_reached | Você já tem 10 tokens, ativos ou não. Exclua um primeiro. |
| 400 | invalid_workflow | Uma entrada de workflowIds não é um workflow do seu espaço pessoal. |
| 400 | token_workspace_mismatch | Um token vinculado a um espaço de trabalho foi enviado com um cabeçalho X-Nodaro-Workspace que indica outro. |
| 401 | unauthorized | O token está ausente, é inválido ou foi revogado, ou um token OAuth ou um JWT de sessão expirou. Os tokens de API pessoais não expiram. |
| 403 | forbidden | O token tem um escopo de workflows e a requisição está fora dele, ou a rota precisa de uma sessão com login. |
| 403 | access_blocked | No Nodaro Cloud e na Business edition, um administrador bloqueou a conta. Todas as credenciais da conta são recusadas. |
| 403 | insufficient_scope | Um token OAuth não tem um escopo de que a rota precisa. missingScope indica qual. |
| 403 | in_app_only | A rota existe só para o app web do Nodaro. |
| 403 | edition_required | A rota precisa de uma edição superior. required_edition indica a edição mínima. |
| 403 | api_tokens_payer_only | Em uma implantação com uma única conta de cobrança, só essa conta pode criar tokens. |
| 403 | sso_required | A implantação restringe o login ao provedor de identidade dela, e a conta desta sessão não foi criada por ele. Os tokens de API e os tokens OAuth não são afetados. |
Todos os erros usam o mesmo envelope. Veja Erros para a lista completa.
Perguntas frequentes
Como consigo uma chave de API do Nodaro?
Faça login no Nodaro, abra “Configurações › Tokens de API” e clique em “Criar token”. Dê um nome e um limite de taxa ao token e copie-o. O token começa com ndr_ e só aparece uma vez.
Os tokens de API do Nodaro expiram?
Não. Um token de API pessoal funciona até você desativá-lo ou excluí-lo, e não tem limite de gastos. Guarde o token como uma senha e exclua-o quando não precisar mais dele.
Devo usar um token de API ou OAuth?
Use um token de API pessoal quando o seu próprio servidor chama o Nodaro para a sua própria conta. Use OAuth quando você cria um produto e cada um dos seus usuários conecta a própria conta do Nodaro.
Posso usar a API na Community Edition auto-hospedada?
Sim. Os tokens de API estão disponíveis no Nodaro Cloud e na Business edition. Em uma instalação da Community Edition, envie em vez disso o JWT da sua sessão com login como token Bearer.
Posso chamar a API do Nodaro a partir de um navegador?
Nunca coloque um token de API pessoal no código do navegador, porque qualquer pessoa pode lê-lo ali. Chame o Nodaro a partir do seu próprio servidor ou use OAuth e registre a origem do seu site no app de desenvolvedor.
Páginas relacionadas
Apps OAuth
Espaços de trabalho e organizações
Limites de taxa
Erros
SDK para TypeScript
Última atualização
Visão geral da API REST
A API REST do Nodaro executa workflows e nós avulsos, consulta tarefas periodicamente, envia mídia e gerencia entidades por HTTPS, com JSON e um token Bearer.
Workflows
Execute workflows do Nodaro pela API com novas entradas, aguarde ou consulte periodicamente o resultado; liste, crie, atualize, exporte e mova workflows.