Autenticação

Guia completo de autenticação na API Polar. Chaves de API, escopos, JWT tokens e melhores práticas de segurança.

Visão Geral

A API Polar utiliza chaves de API (API keys) para autenticação. Todas as requisições devem incluir uma chave válida no header Authorization. A plataforma também suporta autenticação via JWT tokens para integrações avançadas com Supabase.

Chaves de API

Formato

Todas as chaves de API da Polar seguem o formato pk- seguido de uma string alfanumérica:

pk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Usando a Chave de API

Inclua a chave no header Authorization usando o esquema Bearer:

curl https://api.polarai.com.br/v1/chat/completions \
  -H "Authorization: Bearer pk-sua-chave-aqui" \
  -H "Content-Type: application/json" \
  -d '{"model": "urso-mabe", "messages": [{"role": "user", "content": "Olá!"}]}'

from openai import OpenAI

client = OpenAI(
    base_url="https://api.polarai.com.br/v1",
    api_key="pk-sua-chave-aqui"
)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.polarai.com.br/v1",
  apiKey: "pk-sua-chave-aqui",
});

Criando Chaves no Dashboard

Acesse o Dashboard Polar
Navegue até Configurações > Chaves de API
Clique em Criar Nova Chave
Defina um nome descritivo e o escopo desejado
Copie a chave imediatamente (ela não será exibida novamente)

Escopos

Cada chave de API pode ter escopos específicos que limitam suas permissões:

Escopo	Descrição	Endpoints
`read`	Apenas leitura	GET, consultas, completions
`write`	Leitura e escrita	POST, PUT, DELETE, criação de recursos
`admin`	Acesso total	Gerenciamento de conta, billing, chaves

Exemplos de Escopo

{
  "key": "pk-abc123...",
  "name": "API Produção",
  "scopes": ["read", "write"],
  "created_at": "2024-01-15T10:00:00Z"
}

Backend de produção: ["read", "write"]
Frontend (apenas consultas): ["read"]
Automação de billing: ["admin"]

JWT Tokens via Supabase

Para integrações avançadas, a Polar suporta autenticação via JWT tokens do Supabase:

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

// Login
const { data: { session } } = await supabase.auth.signInWithPassword({
  email: 'usuario@example.com',
  password: 'senha-segura'
});

// Usar JWT token
const response = await fetch('https://api.polarai.com.br/v1/chat/completions', {
  headers: {
    'Authorization': `Bearer ${session.access_token}`,
    'Content-Type': 'application/json'
  },
  method: 'POST',
  body: JSON.stringify({
    model: 'urso-mabe',
    messages: [{ role: 'user', content: 'Olá!' }]
  })
});

IP Allowlisting

Para maior segurança, restrinja o acesso a IPs específicos:

Acesse Configurações > Segurança > IP Allowlist
Adicione os IPs ou faixas CIDR permitidos
Ative o allowlisting para a chave desejada

{
  "key": "pk-abc123...",
  "ip_allowlist": [
    "203.0.113.0/24",
    "198.51.100.42"
  ],
  "ip_allowlist_enabled": true
}

Melhores Práticas

Use variáveis de ambiente

Nunca inclua chaves de API diretamente no código-fonte:

# .env (NÃO commite este arquivo)
POLAR_API_KEY=pk-sua-chave-aqui

import os

api_key = os.environ.get("POLAR_API_KEY")

Nunca exponha no frontend

Chaves de API nunca devem ser usadas diretamente em código frontend (JavaScript/TypeScript do lado do cliente). Sempre faça as chamadas de API através do seu backend:

// ERRADO - Nunca faça isso no frontend
const client = new OpenAI({
  apiKey: "pk-sua-chave-aqui", // EXPOSTO no browser!
  dangerouslyAllowBrowser: true
});

// CORRETO - Faça via seu backend/API route
// pages/api/chat.ts (Next.js API Route)
export default async function handler(req, res) {
  const client = new OpenAI({
    baseURL: "https://api.polarai.com.br/v1",
    apiKey: process.env.POLAR_API_KEY // Variável de ambiente no servidor
  });
  // ...
}

Rotação de chaves

Rotacione suas chaves periodicamente:

Crie uma nova chave com os mesmos escopos
Atualize suas aplicações para usar a nova chave
Verifique que tudo funciona corretamente
Revogue a chave antiga

Código	Erro	Descrição	Solução
401	`invalid_api_key`	Chave de API inválida	Verifique se a chave está correta e começa com `pk-`
401	`expired_token`	Token JWT expirado	Renove o token via Supabase
403	`insufficient_scope`	Escopo insuficiente	Use uma chave com os escopos necessários
403	`ip_not_allowed`	IP não está no allowlist	Adicione o IP ao allowlist
429	`rate_limited`	Rate limit excedido	Aguarde e tente novamente