Autenticação

A API aceita dois tipos de token no cabeçalho Authorization: Bearer. Os dois passam pelos mesmos escopos e pelo mesmo limite de 60 requisições por minuto.

Chave pessoal ou OAuth

Chave pessoal

Crie em Desenvolvedor > Chaves e envie como token:

curl -H "Authorization: Bearer vxp_..." \
  https://api.vixpi.host/api/v1/services

Uma chave não cria outras chaves nem mexe em apps OAuth e webhooks: essas ações só existem no painel, com login.

OAuth 2.1 passo a passo

O fluxo é o authorization_code com PKCE. O método S256 é obrigatório mesmo para apps com segredo.

1. Crie o app

Em Desenvolvedor > Apps cadastre nome e URIs de redirecionamento. Um app confidencial (tem backend) recebe um client_secret; um app público (navegador, celular) não recebe segredo e depende só do PKCE. O segredo aparece uma única vez.

2. Mande a pessoa autorizar

Gere um code_verifier aleatório, o code_challenge (SHA-256 do verifier, em base64url) e um state:

import { createHash, randomBytes } from 'node:crypto'

const verifier = randomBytes(32).toString('base64url')
const challenge = createHash('sha256').update(verifier).digest('base64url')
const state = randomBytes(16).toString('base64url')
// guarde verifier e state na sessão da pessoa até a volta do redirecionamento

Redirecione o navegador para o endpoint de autorização:

GET https://auth.vixpi.host/oauth2/authorize
  ?response_type=code
  &client_id=SEU_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.exemplo.com%2Fcallback
  &scope=openid%20offline_access%20tickets%3Aread
  &state=<state>
  &code_challenge=<challenge>
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.vixpi.host

• state: confira que volta igual no callback; é a defesa contra CSRF.
• resource: a API que vai receber o token. Sem ele o token não leva o público (aud) que a API exige.
• scope: só o que o app precisa. Inclua offline_access para receber um refresh token.

3. Consentimento

A Vixpi pede login e mostra à pessoa o app e cada escopo em português. Escopos de escrita aparecem em destaque. Se ela aprovar, o navegador volta para a sua redirect_uri com code e state.

4. Troque o código por tokens

No seu servidor, com o code_verifier guardado no passo 2. O código vale uma vez e por pouco tempo.

curl -X POST https://auth.vixpi.host/oauth2/token \
  -d grant_type=authorization_code \
  -d code=CODIGO_DO_CALLBACK \
  -d redirect_uri=https://app.exemplo.com/callback \
  -d client_id=SEU_CLIENT_ID \
  -d client_secret=SEU_CLIENT_SECRET \
  -d code_verifier=<verifier> \
  -d resource=https://api.vixpi.host

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "...",
  "scope": "openid offline_access tickets:read"
}

App público não envia client_secret. O refresh_token só vem quando o escopo offline_access foi aprovado. Chame a API com o access token:

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.vixpi.host/api/v1/tickets

5. Renove com o refresh token

O access token dura 15 minutos. Peça outro antes de expirar, ou quando a API responder 401 INVALID_TOKEN:

curl -X POST https://auth.vixpi.host/oauth2/token \
  -d grant_type=refresh_token \
  -d refresh_token=REFRESH_TOKEN_ATUAL \
  -d client_id=SEU_CLIENT_ID \
  -d client_secret=SEU_CLIENT_SECRET

O refresh token tem rotação: cada renovação devolve um refresh token novo e o anterior deixa de valer. Troque o valor guardado a cada resposta; reapresentar um refresh token já usado é tratado como vazamento e a pessoa precisa autorizar de novo.

6. Revogue

Ao desconectar uma pessoa do seu app, revogue o refresh token. Ela também pode tirar o acesso do app em Apps autorizados. O access token é um JWT e vale até expirar (no máximo 15 minutos); o que a revogação impede é renovar.

curl -X POST https://auth.vixpi.host/oauth2/revoke \
  -d token=REFRESH_TOKEN_ATUAL \
  -d token_type_hint=refresh_token \
  -d client_id=SEU_CLIENT_ID \
  -d client_secret=SEU_CLIENT_SECRET

Endereços

Não grave os endereços no código se a sua biblioteca lê o discovery (RFC 8414 e OpenID Connect). Eles são:

Escopos

Cada rota da referência indica o escopo que exige. Faltou escopo, a API responde 403 INSUFFICIENT_SCOPE. Escopos :write mudam dados e aparecem em destaque no consentimento. Peça o mínimo.

Identidade

Algumas ações não aceitam token de jeito nenhum e só existem no painel: compra e carrinho, pagamento por Pix ou cartão, saque de afiliado, exportação e exclusão de conta e a senha da VPS. Essas rotas respondem 403 TOKEN_NOT_ALLOWED.