Autenticação

A API usa dois valores diferentes, e cada um tem um lugar só:

A chave é criada junto com a credencial, no painel. Veja Credenciais da API.

Troque a chave pelo token

POST /auth/token é a única rota que recebe a chave. Ela não tem corpo e não usa Idempotency-Key.

curl -X POST "https://api.pagpolar.com/v1/auth/token" \
  -H "X-API-Key: <SUA_CHAVE_DE_API>"

const response = await fetch('https://api.pagpolar.com/v1/auth/token', {
  method: 'POST',
  headers: { 'X-API-Key': '<SUA_CHAVE_DE_API>' },
});

console.log(response.status, await response.json());

A URL base da API é https://api.pagpolar.com/v1. Veja Ambientes e URL base.

Resposta 200:

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 86400
  }
}

Contrato completo: POST /auth/token.

Envie o token em Authorization

Todas as outras rotas exigem o header Authorization no formato Bearer <token>. O jeito mais rápido de testar é chamar GET /me:

curl "https://api.pagpolar.com/v1/me" \
  -H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>"

const response = await fetch('https://api.pagpolar.com/v1/me', {
  headers: { Authorization: `Bearer ${accessToken}` },
});

console.log(response.status, await response.json());

Se o token estiver certo, a resposta é 200:

{
  "data": {
    "credential_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "environment": "PRODUCTION",
    "rate_limit_per_minute": 120
  }
}

Contrato completo: GET /me.

Validade do token

O token vale 24 horas a partir da emissão (expires_in: 86400).

Não existe rota de renovação nem refresh token. Quando o token expirar, chame POST /auth/token de novo com a mesma chave.

Guarde o token em memória e reaproveite enquanto ele valer. Pedir um token por requisição gasta uma chamada a mais em cada operação, sem nenhum ganho.

Renove o token quando receber 401

O padrão que funciona: guardar o token em memória, usar enquanto valer e, ao receber 401, pegar um token novo e repetir a chamada uma vez.

const apiUrl = 'https://api.pagpolar.com/v1';

let accessToken = null;

async function obterToken() {
  const response = await fetch(`${apiUrl}/auth/token`, {
    method: 'POST',
    headers: { 'X-API-Key': process.env.PAGPOLAR_API_KEY },
  });

  if (!response.ok) {
    throw new Error(`Falha ao obter o token: ${response.status}`);
  }

  const { data } = await response.json();
  accessToken = data.access_token;

  return accessToken;
}

export async function chamarApi(caminho, options = {}) {
  if (!accessToken) await obterToken();

  const enviar = () =>
    fetch(`${apiUrl}${caminho}`, {
      ...options,
      headers: {
        ...options.headers,
        Authorization: `Bearer ${accessToken}`,
      },
    });

  let response = await enviar();

  if (response.status === 401) {
    await obterToken();
    response = await enviar();
  }

  return response;
}

Em rotas com Idempotency-Key, mantenha a mesma chave de idempotência ao repetir a chamada. Assim a cobrança não acontece duas vezes. Veja Idempotência.

A credencial é conferida em toda requisição

O token não é uma autorização isolada. A cada requisição, a API lê a credencial que está por trás do token e confere status, data de expiração e IPs autorizados.

Na prática:

• Revogar a credencial, editar a credencial ou mudar os IPs autorizados vale a partir da próxima requisição, inclusive para os tokens já emitidos, mesmo dentro das 24 horas.
• Uma credencial revogada ou expirada responde 401 mesmo com um token dentro da validade.

Não existe como revogar um token específico. Para cortar o acesso, revogue a credencial. Como fazer no painel: Revogar uma credencial e Restringir por IP.

Formato da chave

A chave tem quatro partes separadas por _. O segundo pedaço mostra o ambiente:

Os caracteres são hexadecimais: números de 0 a 9 e letras de a a f.

Chaves antigas não têm o pedaço live ou test (pgp_ + 8 caracteres + _ + segredo). Elas continuam válidas em POST /auth/token.

Restrição por IP

Se a credencial tem IPs autorizados, a API só aceita requisições que venham de um desses IPs. A conferência acontece nos dois lugares: em POST /auth/token e em todas as rotas que usam o token.

A API descobre o IP da requisição nesta ordem:

1. o valor do header X-Real-IP;
2. o último IP do header X-Forwarded-For;
3. o IP da conexão.

Cadastre cada IP de saída do seu servidor, um por um. A comparação é exata: o IP da requisição precisa ser igual a um item da lista. Uma faixa de IPs, como 203.0.113.0/24, não é tratada como faixa.

Respostas de erro de autenticação

Todas seguem o formato de erro. O code é unauthorized no 401 e forbidden no 403.

Guarde a chave com segurança

• A chave aparece uma única vez, na criação. Veja O que aparece uma única vez.
• Guarde a chave em uma variável de ambiente ou em um cofre de segredos do seu servidor.
• Nunca coloque a chave nem o token no código do navegador, em aplicativo de celular ou no repositório.
• O token também é um segredo: quem tem o token chama a API no seu lugar até ele expirar.
• Se a chave vazar, revogue a credencial na hora e crie outra.

Próximos passos