# 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.

Source: https://nodaro.ai/pt-BR/docs/developers/api/authentication

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.

```http
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 um cron job 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 self-hosted 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](https://nodaro.ai/docs/developers/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](https://nodaro.ai/docs/concepts/editions).

## 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 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
| 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](https://nodaro.ai/docs/developers/api/workspaces#bind-a-token-to-a-workspace).

## 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**

```bash
curl https://app.nodaro.ai/v1/me \
  -H "Authorization: Bearer $NODARO_API_KEY"
```

```json
{
"data": {
"id": "5bf0d884-47b1-468e-a7b2-2433f957b267",
"email": "ada@example.com",
"displayName": "Ada",
"avatarUrl": null,
"tier": "pro",
"isAdmin": false
}
}
```

**TypeScript SDK**

```ts

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)
```

**CLI**

```bash
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](https://nodaro.ai/docs/developers/api/workspaces).

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

| 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. |
| `workflows:write` | Criar, mudar, importar e excluir workflows. |
| `workflows:execute` | Executar workflows com `POST /v1/workflows/:id/run`. |
| `jobs:read` | Ler o status e os resultados dos jobs, inclusive a consulta periódica em lote. |

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](https://nodaro.ai/docs/developers/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:

| 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](https://nodaro.ai/docs/get-started/workflow-copilot)) | `403 in_app_only` |
| `/v1/http-credentials` (chaves armazenadas para a **Saída de webhook** (Webhook Output)) | `403 in_app_only` |

Para montar workflows por código, use os [endpoints de workflow](https://nodaro.ai/docs/developers/api/workflows), o [SDK](https://nodaro.ai/docs/developers/sdk) ou o [servidor MCP](https://nodaro.ai/docs/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:

```http
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:

```text
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](https://nodaro.ai/docs/self-hosting/cloud-connect).

## 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
| 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, expirou ou foi revogado. |
| 403 | `forbidden` | O escopo de workflows do token não inclui este workflow, ou a rota precisa de uma sessão com login. |
| 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](https://nodaro.ai/docs/developers/api/errors) para a lista completa.

## Frequently asked questions

### 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 self-hosted?

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.