Autenticação da REST API para Portugal
Bearer keys, OAuth2 PKCE e mTLS — autenticação da REST API para clientes em Portugal.
Arquitectura — Chaves API (servidor a servidor)
Gere chaves API no dashboard, com âmbito de país (Portugal) e papel (só leitura, encomendas, facturas, admin). Envie como Authorization: Bearer cm_live_… sobre TLS 1.3. Prefixos por ambiente (cm_live_, cm_test_) e rotação sem downtime com janela de sobreposição de 24h. Nunca incorpore chaves em código client-side — use OAuth2. IVA 23% e outros defaults para Portugal são inferidos do scope da chave mas substituíveis por pedido no campo country.
Como integrar — OAuth2 com PKCE (acesso delegado)
Para apps de utilizador final (mobile, SPA, portais de parceiros) use OAuth2 authorisation code com PKCE (S256). Autorize em https://auth.corpmerch.com/oauth2/authorize, troque o code por um access token (1 hora) e refresh token (30 dias, rotativo). Scopes em least-privilege: orders.read, orders.write, invoices.read etc. Refresh tokens são device-bound; a detecção de roubo invalida a família ao reusar.
Operação e casos extremos — mTLS (tenants de alta segurança)
Clientes empresariais podem exigir mTLS além do bearer. Carregue o certificado de cliente (PEM, RSA 2048 ou ECDSA P-256) via dashboard ou Trust API. Terminamos mTLS na edge em Lisboa, validamos cadeia e SAN contra a config do tenant e só então aceitamos. Rotação de cert via par primary/secondary. A autenticação para Portal das Finanças (AT) fica do nosso lado com as nossas credenciais — o seu mTLS é apenas para a API Corp-Merch.
Perguntas frequentes
Chave ou OAuth — quando?
Servidor-a-servidor no teu DC ou VPC: chave API. Delegação de utilizador final (mobile, portais de parceiros): OAuth2 PKCE. Setups mistos usam ambos.
Como roto uma chave?
Gera uma nova em paralelo, faz deploy, depois revoga a antiga após a janela de 24h. O dashboard mostra last-used timestamps.
mTLS é standard ou pago?
Incluído em Enterprise; add-on em Pro. Cert self-signed aceites com manual pinning; CAs públicas preferidas.
Validade dos tokens?
Access token 1 hora; refresh token 30 dias, com rotação ao usar, com detecção de roubo.
E autenticação para AT?
AT é canal downstream — autenticamo-nos por ti com as nossas credenciais. O routing IVA 23% é transparente.