Autenticação e autorização
A API usa dois passos: (1) trocar a chave pública + secreta por um token Bearer; (2) enviar o token em todas as demais chamadas.
1. Obter o token
POST /api/auth com HTTP Basic: usuário = chave pública, senha = chave secreta.
#!/usr/bin/env bash
# Obter token de acesso (chave pública + chave secreta em HTTP Basic)
set -euo pipefail
: "${SHARKPAY_BASE_URL:?}" "${SHARKPAY_PUBLIC_KEY:?}" "${SHARKPAY_SECRET_KEY:?}"
curl -sS --fail-with-body -X POST "$SHARKPAY_BASE_URL/api/auth" \
-u "$SHARKPAY_PUBLIC_KEY:$SHARKPAY_SECRET_KEY"
echo// Obter token de acesso — Node.js 18+
const basic = Buffer.from(`${process.env.SHARKPAY_PUBLIC_KEY}:${process.env.SHARKPAY_SECRET_KEY}`).toString('base64');
const res = await fetch(`${process.env.SHARKPAY_BASE_URL}/api/auth`, {
method: 'POST',
headers: { Authorization: `Basic ${basic}` },
signal: AbortSignal.timeout(30_000),
});
const data = await res.json().catch(() => ({}));
if (!res.ok) { console.error(res.status, data); process.exit(1); }
// Guarde o token em memória/cofre e renove ao expirar (expires_in, em segundos).
console.log(JSON.stringify(data.success, null, 2));# Obter token de acesso — Python 3.9+ (pip install requests)
import os, sys
import requests
res = requests.post(
os.environ["SHARKPAY_BASE_URL"] + "/api/auth",
auth=(os.environ["SHARKPAY_PUBLIC_KEY"], os.environ["SHARKPAY_SECRET_KEY"]), # HTTP Basic
timeout=30,
)
data = res.json() if res.content else {}
print(res.status_code, data)
sys.exit(0 if res.ok else 1)<?php
// Obter token de acesso — PHP 8+ com ext-curl
$ch = curl_init(getenv('SHARKPAY_BASE_URL') . '/api/auth');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_USERPWD => getenv('SHARKPAY_PUBLIC_KEY') . ':' . getenv('SHARKPAY_SECRET_KEY'), // HTTP Basic
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, ' ', $response, PHP_EOL;
exit($status === 200 ? 0 : 1);| Campo | Tipo | Descrição |
|---|---|---|
| success.token | string | Token de acesso (JWT). Trate como segredo. |
| success.token_type | string | Sempre Bearer. |
| success.expires_in | integer | Validade em segundos (padrão 30 dias; configurável pelo operador do SharkPay). |
| Status | Quando |
|---|---|
| 400 | Cabeçalho ausente, malformado ou chave vazia. |
| 401 | Chaves incorretas. |
| 429 | Mais de 10 tentativas por minuto por IP. Respeite Retry-After. |
2. Usar o token
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...
Content-Type: application/jsonFaça cache do token em memória e renove antes de expires_in (ou ao receber 401, uma única vez, e repita a chamada). Não peça um token novo a cada requisição: o limite de 10/min por IP existe para isso.
Autorização: o que o token permite
- O token representa a sua conta. Todas as consultas são isoladas por conta: pedir a cobrança, o cliente ou o saque de outra conta devolve 404.
- Hoje o token tem acesso total às operações da API da sua conta (não há escopos granulares nem chaves somente-leitura — veja Limitações).
- Cada meio de pagamento precisa estar habilitado na conta (Pix, boleto, cartão). Se não estiver, a criação responde 400.
- Saques Pix movem dinheiro: exigem Idempotency-Key e respeitam o saldo disponível.
Erros de autenticação nas chamadas
{ "message": "Unauthenticated." }Ao receber 401, obtenha um novo token e repita uma vez. Se persistir, verifique se as chaves foram rotacionadas.