Autenticação

Toda requisição à API da Nuvia é autenticada por um token Bearer enviado no header Authorization. Esta página explica como autenticar chamadas com uma API Key que você já possui. Para gerar, listar e revogar chaves, veja o Guia de API Key.

Base URL

https://api.nuvia.ai

Todas as rotas da API REST usam o prefixo de versão /v1. Por exemplo, listar agentes é GET https://api.nuvia.ai/v1/agents.

A API Key da Nuvia não usa um header X-API-Key nem um token no formato sk_.... A chave é enviada como um token Bearer no header Authorization:

Authorization: Bearer <sua-api-key>

Enviar a chave em X-API-Key resulta em 401 — o servidor simplesmente não lê esse header.

Duas formas de autenticar

A API aceita dois tipos de identidade no mesmo header Authorization: Bearer:

API Key de empresa — é o que você usa para integração programática. A chave é vinculada à sua empresa e aos escopos definidos na criação; pode ter validade opcional (expiresAt). É o método recomendado para servidores, scripts e integrações.
JWT humano — o token de sessão emitido pelo fluxo de login do aplicativo (POST /v1/auth/login). Representa um usuário humano, não uma integração. Você não precisa dele para consumir a API via API Key.

O servidor identifica automaticamente qual dos dois foi enviado pelo próprio conteúdo do token — você não sinaliza o tipo em lugar nenhum. Para o resto desta documentação, assumimos o uso de API Key de empresa.

Autenticando uma requisição

Inclua o header Authorization em toda chamada. O exemplo abaixo lista os agentes da sua empresa (requer o escopo agents:read):

curl https://api.nuvia.ai/v1/agents \
  -H "Authorization: Bearer $NUVIA_API_KEY"

const res = await fetch("https://api.nuvia.ai/v1/agents", {
  headers: {
    Authorization: `Bearer ${process.env.NUVIA_API_KEY}`,
  },
});

const data = await res.json();

import os
import requests

res = requests.get(
    "https://api.nuvia.ai/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
)

data = res.json()

A API Key é um token de acesso completo ao escopo concedido. Trate-a como um segredo: guarde em variável de ambiente ou cofre de segredos, nunca no código-fonte nem no controle de versão.

Multi-tenant e o header `X-Company-Id`

O tenant (empresa) de uma API Key de empresa é resolvido pelo próprio token — você não precisa informá-lo. O header X-Company-Id só é obrigatório para chaves globais de uso interno e é ignorado para API Keys de empresa e para JWT humano. Em resumo: integrando com uma API Key de empresa, você não envia X-Company-Id.

Erros de autenticação

As respostas de erro de autenticação seguem o formato { statusCode, message, error }.

401 — não autenticado

Retornado quando o token está ausente, é inválido, expirou ou foi revogado.

{
  "statusCode": 401,
  "message": "Autenticação inválida",
  "error": "Unauthorized"
}

O campo message detalha a causa quando possível — por exemplo "API Key inválida", "API Key expirada", "API Key revogada" ou "API Key não encontrada".

403 — sem permissão

Retornado quando o token é válido, mas a API Key não tem o escopo necessário para a ação, ou o endpoint não está disponível para API Keys.

{
  "statusCode": 403,
  "message": "API Key não possui o escopo necessário para esta ação",
  "error": "Forbidden"
}

Se você recebe 403 em uma chamada que deveria funcionar, verifique se a chave foi criada com o escopo exigido pelo endpoint. Os escopos são definidos no momento da criação da chave — veja o Guia de API Key.

Primeiros passos

Guias

Base URL

Duas formas de autenticar

Autenticando uma requisição

Multi-tenant e o header `X-Company-Id`

Erros de autenticação

401 — não autenticado

403 — sem permissão

Próximos passos

Guia de API Key

Início rápido

​Base URL

​Duas formas de autenticar

​Autenticando uma requisição

​Multi-tenant e o header X-Company-Id

​Erros de autenticação

​401 — não autenticado

​403 — sem permissão

​Próximos passos

Guia de API Key

Início rápido

Base URL

Duas formas de autenticar

Autenticando uma requisição

Multi-tenant e o header `X-Company-Id`

Erros de autenticação

401 — não autenticado

403 — sem permissão

Próximos passos