Autenticação.
Três modos, mesmas credenciais. OAuth 2.0 pra server-to-server, API Key pra sandbox, mTLS pra Banking — você escolhe o escopo, não o produto.
OAuth 2.0 API Key mTLS Scopes
access_token com escopo definido. O token expira em 1h por padrão.A API Unificada Stone suporta três modos de autenticação. Você usa o mesmo client_id / client_secret em todos os produtos — o que muda é o escopo (scopes) que sua aplicação solicita no token.
OAuth 2.0 — Client Credentials
Recomendado pra todos os fluxos server-to-server. Troque suas credenciais por um access_token de curta duração e use-o no header Authorization.
cURL
curl -X POST https://api.stone.com.br/oauth/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d "grant_type=client_credentials" \
-d "scope=payments.write banking.read"
Node.js
import Stone from '@stone/node';
const client = new Stone({
clientId: process.env.STONE_CLIENT_ID,
clientSecret: process.env.STONE_CLIENT_SECRET,
environment: 'production'
});
// O SDK gerencia o token e renova antes de expirar.
Python
from stone import Stone
client = Stone(
client_id=os.environ["STONE_CLIENT_ID"],
client_secret=os.environ["STONE_CLIENT_SECRET"],
)
Resposta:
{
"access_token": "eyJhbGci...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "payments.write banking.read"
}
API Key — sandbox e leitura
Para protótipos e ferramentas de leitura. Não use em produção para escrita.
curl https://sandbox.api.stone.com.br/v1/charges \
-H "Authorization: Bearer sk_test_4eC39Hq..."
mTLS — obrigatório em Banking
Endpoints regulados pelo BCB (Pix recebido, transferências, abertura de conta) exigem certificado digital ICP-Brasil A1 ou A3.
Escopos disponíveis
| Escopo | Produtos |
|---|---|
payments.read / payments.write | Checkout, Stone Online, AutoTEF |
banking.read / banking.write | Conta Stone (Pix, transferências, boletos) |
pos.manage | Connect Stone, SDK Android — gestão de terminais |
webhooks.manage | Cadastro/listagem de webhook endpoints |
Boas práticas
Uma app por contexto
Nunca logue o token