Autenticação
Como autenticar nas ferramentas com token de API, escopos e requisitos de conta.
Token de API
Todas as rotas em /v1/tools/* exigem um token de API, criado no dashboard em APIs.
| Forma | Exemplo |
|---|---|
| Header dedicado (recomendado) | X-API-Token: rsk_live_... |
| Authorization | Authorization: ApiKey rsk_live_... |
| Authorization (alternativo) | Authorization: Token rsk_live_... |
Boas práticas
Guarde o token na variável de ambiente RESPAWN_API_TOKEN, crie um token por integração com os escopos mínimos necessários e revogue os que não usar mais.
Requisitos da conta
Antes de qualquer chamada às ferramentas, a conta precisa ter:
- E-mail verificado — caso contrário,
auth.email_not_verified(403). - Saldo não negativo — conta suspensa retorna
billing.user_bankrupt(402). - Créditos suficientes — operações pagas sem saldo retornam
billing.insufficient_credits(402).
Escopos
Cada rota aceita um conjunto de escopos; basta o token ter um deles. Se faltar permissão, a API retorna scope.missing (403) com details.required e details.provided. Os escopos aceitos por cada endpoint aparecem no card do endpoint.
| Escopo | Permite |
|---|---|
tools:manage | Acesso total a todas as ferramentas (inclui leitura e escrita). |
tools:read | Leitura genérica de QR Dinâmico, Verificação de URL, Base de conhecimento, Webhook Relay, Extrator de erro de CI e Página web para Markdown. Não cobre PDF. |
tools:qr:dynamic:read | Listar, consultar e ver analytics de QR Dinâmico. |
tools:qr:dynamic:manage | Criar, editar, ativar/desativar e excluir QR Dinâmico (também permite leitura). |
tools:qr:domains:manage | Cadastrar, editar, verificar e remover os domínios próprios do QR Dinâmico (domínios ativos são cobrados). |
tools:pdf:read | Listar, consultar status e baixar conversões de PDF. |
tools:pdf:manage | Converter, criar batch e reprocessar falhas de PDF. |
tools:safety:read | Consultar a Verificação de URL e o proxy de favicon. |
tools:ci:read | Extrair as linhas de erro de um log de CI. |
tools:web:read | Converter páginas web em Markdown (para gravar o resultado numa base, exige também `tools:rag:manage`). |
tools:rag:read | Ler bases de conhecimento: listar bases, documentos, seções e feedback. |
tools:rag:query | Buscar nas bases de conhecimento: fazer buscas, rerank e registrar feedback de relevância. |
tools:rag:manage | Gerenciar bases de conhecimento: criar, alterar e excluir bases e documentos (também permite ler e buscar). |
tools:webhooks:read | Ler a configuração do Webhook Relay (projetos, endpoints, tipos de evento, fontes, rotas e canvas), o uso do mês e o log de mensagens. |
tools:webhooks:send | Enviar mensagens pelo Webhook Relay (envio único e em lote). Não permite ler nem alterar a configuração. |
tools:webhooks:manage | Gerenciar o Webhook Relay: projetos, endpoints, secrets, tipos de evento, fontes, rotas, layout do canvas, eventos de teste, reenvios e recuperação (também permite ler e enviar). |
tools:realtime:publish | Publicar mensagens em canais do Realtime pela API. |
tools:realtime:subscribe | Ler o histórico e a presença dos canais do Realtime. |
tools:realtime:manage | Gerenciar o Realtime: emitir tokens, consultar canais e estatísticas, configurar o webhook de canais, publicar e ler o histórico e a presença. |
tools:notify:send | Enviar notificações pelo canal padrão ou por um canal escolhido. |
tools:notify:manage | Gerenciar os canais de notificação (criar, alterar, testar e excluir) e ler o histórico de envios. |
tools:learnings:read | Recuperar aprendizados salvos na Memória de aprendizados. |
tools:learnings:write | Salvar e esquecer aprendizados na Memória de aprendizados. |
tools:video:render | Renderizar vídeos (cobrado por segundo renderizado) e validar o roteiro (`validate_video`, `preview_video_frame`). |
tools:video:read | Listar renders de vídeo, consultar o status e obter o link do MP4. |
tools:audio:transcribe | Transcrever áudio (cobrado por minuto), resumir e traduzir transcrições. |
tools:audio:read | Listar os jobs de áudio, consultar o status e obter o link do resultado, além do catálogo de vozes. |
tools:audio:speak | Gerar fala a partir de texto (por 1.000 caracteres), sons e músicas (por segundo) e falar uma gravação de novo com outra voz; no MCP, também criar e apagar vozes clonadas. |
tools:audio:process | Analisar e converter áudio (cobrado por chamada e por minuto). |
mcp:use | Uso por agentes de IA: permite usar a chave no servidor MCP. |
account:read | Ler saldo e limites: consultar o saldo de créditos e o limite diário de gasto. |
PDF é mais restritivo na leitura
Rotas de leitura de PDF aceitam apenas tools:pdf:read ou tools:manage. O escopo genérico tools:read e o tools:pdf:manage não dão acesso à leitura de PDF.
Combinações recomendadas
| Caso de uso | Escopos sugeridos |
|---|---|
| Gerar e gerenciar QR codes | tools:qr:dynamic:manage |
| Painel somente leitura de QRs | tools:qr:dynamic:read |
| Pipeline de PDF | tools:pdf:manage + tools:pdf:read |
| Verificar URLs antes de exibir | tools:safety:read |
| Assistente que busca na base de conhecimento | tools:rag:query |
| Enviar e manter documentos da base | tools:rag:manage |
| Agente de IA (MCP) | mcp:use + os escopos das ferramentas que ele vai usar + account:read |
| Integração completa | tools:manage (mais simples, menos seguro) |
Controles da chave
Além dos escopos, cada token pode ter controles configurados no dashboard. Eles valem em qualquer canal, na API e no MCP:
- Expiração: depois da data, o token para de funcionar (
auth.unauthorized). - Limite diário de gasto: uma cobrança que passaria do limite do dia é recusada com
billing.spend_limit_reached(402), comdetails.limit,details.spent_todayedetails.required. O contador zera à meia-noite UTC. - Restrição por base de conhecimento: o token só enxerga as bases escolhidas; as outras respondem
not_found, e ele não pode criar bases novas (forbidden). - Modelos prontos: ao criar a chave, "Somente leitura", "Agente de suporte" e "Agente completo" preenchem escopos e controles de uma vez.
Expiração, limite e bases podem ser alterados depois; os escopos, não. Para mudar escopos, crie outra chave.
Erros de autenticação
| Código | HTTP | Quando |
|---|---|---|
auth.missing_token | 401 | Header de autenticação não enviado. |
auth.invalid_token | 401 | Token malformado. |
auth.unauthorized | 401 | Token inválido, expirado ou revogado. |
auth.email_not_verified | 403 | E-mail da conta ainda não verificado. |
scope.missing | 403 | Token sem o escopo exigido pela rota (details.required, details.provided). |
tool.disabled | 403 | A ferramenta ainda não está liberada para a conta: está desligada ou em testes com contas selecionadas. Ferramentas com código próprio (como rag.disabled) respondem com ele. |
forbidden | 403 | A chave não pode fazer esta ação (ex.: chave restrita a bases de conhecimento específicas tentando criar uma base). |
Dashboard vs. token de API
- Dashboard — a navegação no painel não consome a franquia diária nem debita leituras medidas.
- Token de API — leituras medidas compartilham a franquia diária de 2.000 requisições (4.000 em contas premium). Depois disso, cada leitura debita créditos.
Exemplo
Criar um QR com dry-run para validar o token, os escopos e o custo sem debitar nada:
curl -sS -X POST 'https://api.respawntech.dev/v1/tools/image/qr-code/dynamic' \
-H "X-API-Token: $RESPAWN_API_TOKEN" \
-H 'X-Dry-Run: true' \
-H 'X-Include-Cost: true' \
-H 'Content-Type: application/json' \
-d '{
"name": "Campanha",
"target_url": "https://example.com"
}'const response = await fetch('https://api.respawntech.dev/v1/tools/image/qr-code/dynamic', {
method: 'POST',
headers: {
'X-API-Token': process.env.RESPAWN_API_TOKEN,
'X-Dry-Run': 'true',
'X-Include-Cost': 'true',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"name": "Campanha",
"target_url": "https://example.com"
}),
});
if (!response.ok) throw new Error((await response.json()).error.code);
console.log(await response.json());import os
import requests
response = requests.post(
"https://api.respawntech.dev/v1/tools/image/qr-code/dynamic",
headers={
"X-API-Token": os.environ["RESPAWN_API_TOKEN"],
"X-Dry-Run": "true",
"X-Include-Cost": "true",
},
json={
"name": "Campanha",
"target_url": "https://example.com"
},
timeout=30,
)
if not response.ok:
raise RuntimeError(response.json()["error"]["code"])
print(response.json())<?php
$ch = curl_init('https://api.respawntech.dev/v1/tools/image/qr-code/dynamic');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'X-API-Token: ' . getenv('RESPAWN_API_TOKEN'),
'X-Dry-Run: true',
'X-Include-Cost: true',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"name": "Campanha",
"target_url": "https://example.com"
}
JSON,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status >= 400) {
throw new RuntimeException(json_decode($body, true)['error']['code']);
}
print_r(json_decode($body, true));package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
"time"
)
func main() {
req, err := http.NewRequest("POST", "https://api.respawntech.dev/v1/tools/image/qr-code/dynamic", strings.NewReader(`{
"name": "Campanha",
"target_url": "https://example.com"
}`))
if err != nil {
panic(err)
}
req.Header.Set("X-API-Token", os.Getenv("RESPAWN_API_TOKEN"))
req.Header.Set("X-Dry-Run", "true")
req.Header.Set("X-Include-Cost", "true")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{Timeout: 30 * time.Second}
res, err := client.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
data, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
if res.StatusCode >= 400 {
panic(string(data))
}
fmt.Println(string(data))
}Atualizado em