Pular para o conteúdo principal
Deixe as pessoas entrarem com o Phaseo e gastarem os próprios créditos no seu aplicativo: o OAuth 2.1 com PKCE dá ao seu servidor um token de acesso, e um único proxy no servidor o anexa a cada chamada ao Gateway. No fim, você tem um aplicativo local com login, tokens guardados na sessão que se renovam, descoberta de modelos, um fluxo de chat sobre /responses e um testador para outros endpoints. O exemplo descobre os endpoints OAuth do Phaseo, verifica state e iss no retorno, renova os tokens com segurança e revoga a chave quando a pessoa sai da conta. Para que um agente de programação crie o mesmo aplicativo do zero, cole este prompt:

Crie um workbench Next.js com login usando OAuth e um proxy unificado do Phaseo.

Abrir no Cursor

Como o exemplo é montado

O exemplo fica em examples/oauth-client-nextjs: Separar o login das chamadas ao Gateway faz com que um problema de login nunca pareça um problema de modelo, e todos os endpoints compartilham um único lugar que trata os tokens.

Execute

Você precisa do Node.js, de um aplicativo OAuth com http://localhost:3000/auth/callback (ou o seu próprio callback) como URI de redirecionamento e de um segredo de sessão longo e aleatório. Crie o aplicativo OAuth em Configurações → Aplicativos OAuth ou com a API de clientes OAuth.
1

Instale

2

Crie o .env.local

Preencha os valores:O exemplo lê todas elas só no servidor. Nunca coloque o segredo de cliente nem o segredo de sessão em uma variável NEXT_PUBLIC_.O exemplo encontra os endpoints de autorização, token, revogação e userinfo em https://api.phaseo.app/.well-known/oauth-authorization-server e pede openid email profile gateway:access. O gateway:access permite que o token chame o Gateway.
3

Inicie o servidor de desenvolvimento

Abra http://localhost:3000, entre e abra o painel.

Confira se funcionou

  • O login volta para a sua URL de callback e cria uma sessão.
  • O painel lista os modelos por meio de /api/gateway/models.
  • Uma rodada de chat por /api/gateway/responses recebe uma resposta, e nenhuma solicitação do navegador carrega o token de acesso.
  • Um caminho fora da lista de permissões do proxy é rejeitado.

Duração dos tokens

O endpoint de token retorna dois tokens:
  • Troque a cada renovação. Cada renovação retorna um novo token de acesso e um novo token de renovação. Guarde os dois e descarte os antigos: o token de acesso antigo para de funcionar na hora, e o token de renovação antigo não pode ser usado de novo.
  • Renove depois da expiração. Você pode renovar depois que o token de acesso expirar, desde que o token de renovação não tenha expirado.
  • Nunca reutilize um token de renovação. Usá-lo uma segunda vez encerra o login. O Phaseo o trata como um token vazado e revoga o token de acesso e todos os tokens de renovação daquele login, então a pessoa precisa entrar de novo.
  • Os escopos só diminuem. Uma renovação nunca adiciona escopos. Ela mantém os escopos que a pessoa aprovou, menos os que ela tiver removido desde então.
  • Quando a renovação falha. A renovação falha quando a pessoa revoga o seu aplicativo, revoga ou desativa a chave dele, remove um escopo de que a chave precisa (como gateway:access) ou sai do espaço de trabalho. Remover gateway:access também revoga a chave, então o token de acesso dela para de funcionar na hora. Conceder o escopo de novo não traz o token de renovação de volta. Mande a pessoa pelo login de novo.
  • Entrar de novo renova a chave. O login renova a mesma chave em vez de adicionar outra, enviando ou não resource=https://api.phaseo.app/v1. Você recebe um novo token de acesso e um novo token de renovação, os anteriores param de funcionar, e a chave mantém os gastos deste mês. O limite de gastos mensal passa a ser o que a pessoa acabou de aprovar. O token de renovação de um login anterior é simplesmente recusado, e enviá-lo ao endpoint de token ou de revogação não encerra o novo login.
  • Uma chave pausada bloqueia o login. Se alguma das chaves do seu aplicativo para aquela pessoa e aquele espaço de trabalho estiver pausada, qualquer que seja o recurso, o endpoint de token retorna invalid_grant até alguém reativar a chave em Configurações → Chaves de API. A renovação só funciona enquanto a chave não estiver revogada: depois de sair da conta ou de qualquer outra revogação, o login emite uma nova chave, e os limites e gastos dela começam do zero.
  • Saia da conta com a revogação. Envie o token de renovação para https://api.phaseo.app/oauth/revoke. Isso revoga a chave e todos os tokens de renovação do login, inclusive um que uma renovação tenha emitido um instante antes.

Limites de gastos

Na tela de consentimento, a pessoa define um limite de gastos mensal para o seu aplicativo: $20.00 por padrão, outro valor ou nenhum limite. Quando a chave gasta esse valor em um mês do calendário, as solicitações ao Gateway retornam 429 com key_limit_exceeded até o mês seguinte ou até a pessoa aumentar o limite em Configurações → Chaves de API. Quaisquer que sejam os escopos que tiver, o seu aplicativo não pode remover esse limite nem contorná-lo pela API. Ele só pode renomear ou excluir chaves de API. Ele não pode criar nem rotacionar chaves, mudar os limites, o status ou a expiração de uma chave, criar chaves de gerenciamento ou cargas de trabalho confiáveis, adicionar membros, mudar orçamentos, guardrails, limites de taxa ou regras de gastos, nem mudar os limites de preço do espaço de trabalho para o roteamento ou o fallback do BYOK para créditos.

Antes de publicar

  • Reduza a lista de permissões. O lib/gateway.ts permite os caminhos que o workbench chama, além do status de jobs em videos/ e music/generate/. Mantenha só os caminhos que o seu produto chama.
  • Compartilhe as renovações entre instâncias. O lib/oauth.ts compartilha em memória uma única renovação entre requisições paralelas. Se você roda mais de uma instância do servidor, mova isso para um armazenamento compartilhado; caso contrário, duas instâncias podem renovar com o mesmo token e encerrar o login.
  • Envie a conversa inteira. O Gateway não armazena respostas e rejeita previous_response_id, então reenvie as rodadas anteriores em input.
  • Substitua o testador. Mantenha o workbench para QA interno e crie fluxos específicos para os usuários finais.
Para um aplicativo com chave de API e sem login, comece pelo aplicativo de chat web com Next.js.
Última modificação em 13 de novembro de 2026