Autenticação

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 self-hosted da Community Edition.

Authorization: Bearer ndr_4f1c…

Qual credencial usar

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

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 com escopo só pode executar e inspecionar esses workflows, e qualquer outro workflow responde 403 forbidden. Uma lista vazia significa que o token pode executar todos os workflows que são seus.

Defina o escopo com o campo workflowIds ao criar ou atualizar um token pelos endpoints abaixo. 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.

Gerenciar tokens por código

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 status

Em 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:

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 self-hosted, 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:

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.

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:

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 job que a requisição criar:

X-Nodaro-Client: sdk/1.10.0

Só 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: esses jobs ficam registrados 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 edge function 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 API

No 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 self-hosted com um token

Um token de API pessoal também é o jeito mais simples de executar as gerações de uma instalação self-hosted no Nodaro Cloud. Na instalação self-hosted, 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/api diretamente.
• 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 respondem 403 payer_required.

Erros

Todos os erros usam o mesmo envelope. Veja Erros para a lista completa.