A conexão com o Supabase liga a Toca ao projeto do seu app ou do seu site: as tabelas do banco e os arquivos do Storage. São quatro jeitos de conectar, todos no mesmo card. O mais simples é Entrar com o Supabase: você autoriza no Supabase, volta à Toca e escolhe o projeto. Também dá para usar um token de acesso da sua conta do Supabase, ou colar a chave do projeto: a chave secreta, ou a chave publicável com um papel dedicado à Toca no banco.
Esta integração está em homologação: a conexão funciona normalmente, mas as consultas no chat ainda estão em validação.
O que a tela do Supabase pede. O Supabase autoriza aplicativos por organização, então a tela de autorização pede acesso à organização inteira: ver os projetos e as chaves deles. A Toca usa esse acesso uma vez só: lê a chave secreta do projeto que você escolher, guarda só essa chave e desfaz a autorização logo em seguida. Nada da organização fica guardado. Com o token de acesso é igual: a Toca lê a chave do projeto e não guarda o token.
Nesses dois caminhos a Toca fica com a chave secreta do projeto, que dá acesso total aos dados e ignora o RLS (Row Level Security). Para escolher, tabela por tabela, o que a Toca vê e altera, use o papel dedicado.
Antes de começar
- Use uma conta do Supabase com acesso ao projeto e que veja as chaves dele em Project Settings → API Keys. Se a sua conta não vê a chave secreta, a Toca também não vê.
- Recomendado: crie antes uma chave secreta só para a Toca, chamada
toca, em Project Settings → API Keys. Entrando com o Supabase ou com o token de acesso, a Toca usa a chave com esse nome; sem ela, usa adefaultou a única que houver. Com a chavetoca, você tira o acesso da Toca apagando só ela, sem mexer nas chaves do seu app. - Para o token de acesso:
- Gere o token nas configurações da sua conta do Supabase, em Access Tokens (
supabase.com/dashboard/account/tokens). Ele começa comsbp_. - Limite o token à organização ou ao projeto que a Toca vai usar e marque só três permissões, todas em leitura: Projects (account-wide), API Keys e API Key Secrets. O guia Personal Access Tokens do Supabase explica como.
- Gere o token nas configurações da sua conta do Supabase, em Access Tokens (
- Para colar a chave do projeto:
- Copie a URL do projeto, no botão Connect do painel ou em Integrations → Data API. Ela tem o formato
https://abcdefghijklmnopqrst.supabase.co. - Chave secreta: copie a chave secreta (ela começa com
sb_secret_) em Project Settings → API Keys. Ela dá acesso total aos dados do projeto e ignora o RLS. - Papel dedicado: a Toca só enxerga e altera o que você liberar. Pede alguém que rode SQL no banco e use a CLI do Supabase. Os passos estão logo abaixo.
- Copie a URL do projeto, no botão Connect do painel ou em Integrations → Data API. Ela tem o formato
Como criar o papel dedicado. No SQL Editor do Supabase, rode o SQL abaixo, trocando pedidos pelas tabelas que a Toca pode ver e notas pelos buckets do Storage. Tire o trecho de escrita se quiser a Toca só lendo.
-- O papel da Toca
create role toca;
grant toca to authenticator;
grant anon to toca;
-- Leitura de uma tabela (repita para cada tabela)
grant select on public.pedidos to toca;
create policy "Toca lê pedidos" on public.pedidos
for select to toca using (true);
-- Escrita na mesma tabela (opcional: tire se a Toca só vai ler)
grant insert, update, delete on public.pedidos to toca;
create policy "Toca insere pedidos" on public.pedidos
for insert to toca with check (true);
create policy "Toca altera pedidos" on public.pedidos
for update to toca using (true) with check (true);
create policy "Toca apaga pedidos" on public.pedidos
for delete to toca using (true);
-- Arquivos de um bucket do Storage (repita para cada bucket)
create policy "Toca vê os buckets" on storage.buckets
for select to toca using (true);
create policy "Toca lê o bucket notas" on storage.objects
for select to toca using (bucket_id = 'notas');
Depois, gere o token do papel toca com a CLI do Supabase (supabase gen bearer-jwt --role toca), seguindo a seção “How to create (mint) JWTs” do guia JWT Signing Keys do Supabase. O token tem prazo de validade: anote quando ele vence. Copie também a chave publicável (sb_publishable_...) em Project Settings → API Keys.
Passo a passo
- Acesse
Configurações → Integraçõesna Toca. - Localize o card Supabase e clique em Conectar.
- Escolha um caminho:
- Entrar com o Supabase (recomendado): clique no botão. Na janela do Supabase, escolha a organização do projeto e autorize. De volta à Toca, o card mostra os projetos da organização: escolha um e clique em Usar seguido do nome do projeto. Se a organização tiver um projeto só, a Toca conecta direto. A escolha vale por 15 minutos, e Cancelar desfaz a autorização.
- Token de acesso: cole o token no campo Token de acesso e clique em Buscar projetos. Escolha o projeto e clique em Usar seguido do nome do projeto.
- Chave do projeto: abaixo de “ou cole a chave do projeto”, preencha URL do projeto, Chave de API (a secreta,
sb_secret_..., ou a publicável,sb_publishable_..., no papel dedicado) e Token do papel dedicado (deixe em branco com a chave secreta). Clique em Salvar chave.
- O card fica marcado como conectado. Nos dois primeiros caminhos, ele diz qual chave secreta e qual projeto a Toca usa.
O que a Toca acessa
Com a conexão ativa, a Toca lê as linhas das tabelas e views que o acesso alcança (pedidos, leads, cadastros, clientes ou o que o seu banco guardar), as funções de consulta do banco, os buckets do Storage e a lista de arquivos com os metadados. Para um arquivo, ela gera um link assinado para baixar, com validade de até 7 dias: o conteúdo não passa pela Toca.
A Toca também altera as tabelas: insere linhas, atualiza pela coluna única (upsert), altera e apaga as linhas escolhidas por um filtro e executa funções do banco. Toda alteração só acontece mediante sua aprovação explícita, pedido a pedido, dentro do chat. O pedido de aprovação mostra a tabela, o filtro e quantas linhas ele pega hoje.
Algumas travas: alterar ou apagar sem filtro (a tabela inteira) é recusado, e apagar linha ou executar função não se desfaz, o que o pedido de aprovação diz. No Storage a Toca só lê: subir, apagar ou mover arquivo continua no painel do Supabase. Os usuários do login do app (Auth), as Edge Functions e as configurações do projeto e da organização ficam fora: depois de conectar, a Toca só fala com as tabelas e o Storage do projeto escolhido.
Manutenção da conexão
As chaves valem até você apagá-las em Project Settings → API Keys. Apagar a chave que a Toca usa corta o acesso dela; se for a default, corta também o de quem mais a usa, por isso a chave toca é a recomendada. Para trocar de chave ou de projeto, abra o card pelo botão Gerenciar e use Trocar pelo Supabase, o token de acesso ou a chave colada.
Se você fechar a tela sem escolher o projeto nem cancelar, a Toca apaga em 15 minutos o acesso que recebeu do Supabase. O token de acesso não fica com a Toca: depois de conectar, você pode apagá-lo no Supabase.
O token do papel dedicado vence na data que ele traz, e a Toca avisa essa data quando ele vence. Gere outro token, abra o card pelo botão Gerenciar, cole o novo e clique em Atualizar. Por segurança, os valores salvos aparecem mascarados. Para liberar mais uma tabela ou bucket ao papel dedicado, rode de novo o trecho do SQL com o nome dele; o token continua o mesmo.
Para passar da chave secreta para o papel dedicado, atualize a chave e o token no card. Para o caminho contrário, use Excluir integração no menu ⋯ do card e conecte de novo.
Problemas comuns
- O projeto ainda não tem chave secreta — crie uma chamada
tocaem Project Settings → API Keys e escolha o projeto de novo. - O projeto tem várias chaves secretas — sem uma chamada
tocaoudefault, a Toca não adivinha qual usar. Crie atocae escolha o projeto de novo. - O Supabase não mostrou a chave secreta — no token de acesso, falta a permissão API Key Secrets em leitura. No login, a sua conta precisa ver as chaves do projeto.
- Nenhum projeto apareceu — no login, autorize a organização do projeto (a tela do Supabase deixa escolher). No token de acesso, confira a organização ou o projeto e a permissão Projects (account-wide) em leitura.
- A escolha expirou — ela vale 15 minutos. Clique em Entrar com o Supabase de novo.
- URL recusada — a Toca aceita a URL do projeto, terminada em
.supabase.co. O endereço do painel (supabase.com/dashboard/...) não serve. Se o seu projeto usa domínio próprio, fale com o suporte da Toca. - A tabela volta vazia — com o papel dedicado, falta a política de leitura da tabela para o papel
toca(ocreate policy ... for select to tocado SQL acima). Com o RLS ligado e sem política, o banco devolve a lista vazia, sem erro. - Permissão negada (código 42501) — falta o
grantda tabela para o papeltoca, comogrant select on public.pedidos to toca. - Token do papel vencido — gere outro token para o papel
tocae atualize no card. - Tabela fora do schema public — o schema precisa estar exposto na Data API do Supabase (Integrations → Data API). No chat, diga à Toca o nome do schema.
- Conectou o projeto errado — abra o card pelo botão Gerenciar e use Trocar pelo Supabase, ou use Excluir integração no menu ⋯ do card e conecte de novo.