Autenticação na API (clientes máquina, tokens SCIM, clientes OIDC)

Cada superfície de integração tem a sua credencial. Não há chaves de API de longa duração com poderes de administrador.

Clientes máquina (pedidos de aprovação)

O administrador cria o cliente em «Gerir» › «Pedidos de terceiros» e entrega o ID (UUID) e o segredo (agcs1_…). O sistema troca-os por um token de cinco minutos:

curl -sS -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials -d "scope=intents:write intents:read" \
  https://identity.example.com/v1/machine/token

Resposta: {"access_token":"agm1_…","token_type":"Bearer","expires_in":300,"scope":"…"}.

• Só client_secret_basic é aceite.
• Erros RFC 6749: invalid_client (com WWW-Authenticate: Basic realm="authguard-machine"), invalid_request, unsupported_grant_type, invalid_scope.
• Peça um token novo em vez de o guardar para lá dos cinco minutos.
• Um token máquina nunca abre uma rota humana, e uma sessão de navegador nunca abre uma rota máquina.
• Um âmbito em falta dá 403 insufficient_scope.

Tokens SCIM

agscim1_ seguido de 64 hexadecimais, enviados como Authorization: Bearer. Âmbitos scim:users e scim:groups. Token em falta, errado, expirado ou revogado dá sempre o mesmo 401.

Clientes OIDC

Um serviço confidencial autentica-se no endpoint de token com client_secret_basic, client_secret_post ou private_key_jwt; um serviço público usa PKCE sem segredo. Ver Integrar por OIDC.

Boas práticas

• Guarde segredos num cofre, nunca no código.
• Rode-os periodicamente e sempre que uma pessoa com acesso sair.
• Nunca envie segredos ao suporte.