> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# API pública, chaves e webhooks

A superfície REST versionada sobre a qual os teus clientes constroem.

## Antes de começar

Abra seu projeto supastack baixado em Visual Studio Code usando Arquivo → Abrir pasta e escolha Terminal → Novo Terminal. A raiz do repositório é a pasta que contém package.json, apps e pacotes. Execute o comando abaixo e deixe seu terminal aberto. Se um comando não for reconhecido, conclua o guia de instalação da ferramenta antes de continuar.

Leia o tutorial da plataforma primeiro. Um servidor é o processo do aplicativo que responde às solicitações do navegador ou do telefone. A Web lê apps/web/.env.local, Expo lê apps/mobile/.env.local e os comandos de migração de banco de dados leem root .env. A demonstração sem banco de dados/painel é separada das contas reais/auth, que precisam migrar para Postgres. Uma finalização de compra somente por telefone ou desktop precisa de um back-end da Web executado separadamente.

[Instale as ferramentas e obtenha o código](https://supastack.dev/pt/docs/web/before-you-start.md)

[Aprenda comandos, arquivos e configuração](https://supastack.dev/pt/docs/web/terminal-basics.md)

[Conclua o tutorial inicial da Web](https://supastack.dev/pt/docs/web/ship-in-5-minutes.md)

```
corepack pnpm --filter @supastack/web dev
```


## Instalação e configuração

O packages/api define o contrato versionado: schemas zod para cada pedido e resposta, o envelope de erro e o documento OpenAPI servido em /api/v1/openapi e renderizado em /api/docs. As chaves de API do workspace criam-se em Definições → Programadores; o texto em claro mostra-se uma vez, depois persiste apenas a chave com hash.

As chaves têm prefixo (sk_<env>_…), scope (leitura por predefinição) e resolvem para um workspace em cada pedido. As subscrições de webhooks de saída gerem-se na mesma superfície de Programadores.

```
GET  /api/v1/workspaces/current
GET  /api/v1/entitlements
GET  /api/v1/models/requirements
POST /api/v1/ai-tasks
GET  /api/v1/openapi           # machine-readable spec
GET  /api/docs                 # rendered reference

Authorization: Bearer sk_live_…
```


## Fluxo de implementação

Autentica com a chave Bearer; o servidor resolve o workspace a partir da chave, nunca de um id fornecido pelo cliente. Mantém as formas de resposta versionadas — alterações aditivas dentro de v1, alterações breaking atrás de uma nova versão.

Para webhooks de saída, subscreve um URL de endpoint ao catálogo de eventos; as entregas são assinadas e registadas para que os consumidores possam verificar e reenviar. Usa webhook-events.ts para o catálogo e webhook-delivery.ts para as tentativas.


## Verificação e resolução de problemas

Verifica que uma chave revogada devolve 401, que uma chave com scope insuficiente é negada e que o documento OpenAPI faz parse. Para webhooks, testa a verificação de assinatura, a reentrega após falha e que os payloads de eventos nunca transportam secrets do provider.


## Seguinte

[Armazenamento de ficheiros](https://supastack.dev/pt/docs/web/storage.md)