Referência OAuth2¶

Endereços¶

Uso	URL
Início da autorização	`https://admin.gubee.com.br/#/oauth2/authorize`
Emissão e renovação de token	`https://auth.gubee.com.br/realms/gubee/protocol/openid-connect/token`
API de integração	`https://api.gubee.com.br/integration/*`
Painel: criar e gerenciar apps	Integrações → Meus apps
Painel: apps autorizados pelo seller	Integrações → Apps conectados

Parâmetro	Obrigatório	Valores aceitos
`client_id`	Sim	O `client_id` do app registrado
`redirect_uri`	Sim	Uma das URIs cadastradas, em match exato e URL-encoded
`response_type`	Sim	`code`
`code_challenge`	Sim	Challenge derivado do `code_verifier`
`code_challenge_method`	Sim	`S256`
`state`	Não (recomendado)	Valor aleatório do parceiro, devolvido sem alteração
`nonce`	Não	Repassado sem alteração

Authorization code

Campo	Valor
`grant_type`	`authorization_code`
`client_id`	`client_id` do app
`client_secret`	`client_secret` do app
`code`	O código recebido na `redirect_uri`
`redirect_uri`	A mesma usada na autorização
`code_verifier`	O verifier da mesma sessão

Refresh

Recusas que acontecem antes de o usuário chegar à aprovação. O código vem no corpo da resposta.

Código	HTTP	Significado	Como resolver
`oauthapp.unknownclient`	400	`client_id` não corresponde a nenhum app registrado	Confira o `client_id` copiado do painel
`oauthapp.redirecturi`	400	`redirect_uri` não está entre as cadastradas	Compare caractere a caractere com o cadastro
`oauthapp.pkcerequired`	400	Pedido sem `code_challenge`	Gere o PKCE e envie o challenge
`oauthapp.pkcemethod`	400	`code_challenge_method` diferente de `S256`	Use `S256`
`oauthapp.unsupportedresponsetype`	400	`response_type` diferente de `code`	Use `code`
`oauthapp.disabled`	403	App desativado pelo dono ou pela Gubee	Reative na tela do app ou fale com a Gubee
`oauthapp.alreadyauthorized`	403	O usuário já autorizou este app por outra conta	Revogue em Apps conectados e autorize de novo
`oauthapp.masteraccount`	403	A conta usada não é a que opera o sistema	Autorize com uma conta operacional
`oauthapp.accountnotfound`	403	Conta não encontrada	Confirme a conta usada no login
`oauthapp.scopeempty`	400	App registrado sem nenhuma permissão	Edite o app no painel e defina o que ele acessa

Erro	Causa	Como resolver
`invalid_grant`	`code` já usado, expirado, ou `code_verifier` de outra sessão	Refaça o fluxo desde a autorização
`unauthorized_client`	`client_secret` incorreto, ou app sem permissão para este fluxo	Confira o secret; verifique se ele foi rodado
`invalid_client`	`client_id` não corresponde a nenhum app	Confira o `client_id` copiado do painel

HTTP	Causa	Como resolver
`401`	`access_token` ausente, malformado ou expirado	Envie `Authorization: Bearer <token>`; renove se expirado
`403`	O app não tem permissão para a operação, ou o acesso foi revogado	Leia `required_scope` no corpo: são as permissões aceitas pela operação (Permissões dos apps). Peça nova autorização se o acesso foi revogado

Regra	Detalhe
Fluxo suportado	Authorization code com PKCE `S256`
Esquema da `redirect_uri`	`https` obrigatório; `localhost` e `127.0.0.1` liberados para desenvolvimento
Curinga na `redirect_uri`	Não aceito
Comparação da `redirect_uri`	Exata, incluindo barra final e maiúsculas
URIs por app	Várias, uma por ambiente
Client secret	Um vigente por app; rodar invalida o anterior imediatamente
Interruptores	Dois — do dono e da Gubee; o app só funciona com ambos ligados
Revogação pelo seller	Integrações → Apps conectados
Revogação em massa pelo dono	Tela do app → Revogar todos os sellers