Guia rápido OAuth 2.0 para apps conectadas Cathopic - Central de Ajuda

As Apps Conectadas Cathopic usam OAuth 2.0 Authorization Code com PKCE S256 obrigatório. A mesma aprovação do desenvolvedor também desbloqueia a API comercial da Cathopic, mas as conexões OAuth usam tokens do usuário e o plano do usuário conectado, em vez de chaves de API e cobrança de API por uso.

1. Obter acesso e registrar a aplicação

Envie a solicitação única de acesso do desenvolvedor por meio do formulário de contato. Depois que a Cathopic aprovar a conta por e-mail, abra Configurações → Desenvolvedor / API → aplicações OAuth, crie a aplicação, registre seus callbacks exatos e os escopos necessários e armazene seu segredo de uso único, se for confidencial.

2. Descobrir o servidor de autorização

GET https://cathopic.com/.well-known/oauth-authorization-server

3. Redirecionar o usuário

GET https://cathopic.com/oauth/authorize
    ?client_id=CLIENT_ID
    &redirect_uri=EXACT_CALLBACK
    &response_type=code
    &scope=account.read%20catalog.read%20entitlements.read%20licenses.create%20licenses.read
    &state=UNGUESSABLE_STATE
    &code_challenge=BASE64URL_SHA256_VERIFIER
    &code_challenge_method=S256
    &ui_locales=en

Construa uma única URL; as quebras de linha apenas tornam o exemplo legível. Gere novos valores de estado e PKCE com alta entropia para cada tentativa. ui_locales é opcional e pode solicitar um idioma compatível como en ou es. Se for necessário fazer login, a Cathopic retoma a mesma solicitação de autorização e então mostra a tela de permissões.

4. Validar o callback e trocar o código

Compare o estado retornado antes de trocar o código. A URI de redirecionamento deve corresponder byte a byte.

POST https://cathopic.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=EXACT_CALLBACK&code=CODE&code_verifier=VERIFIER

Aplicações públicas omitem client_secret. Armazene tokens e segredos confidenciais apenas no servidor e criptografe-os em repouso. Tokens de acesso duram 30 minutos; tokens de atualização duram até 30 dias e são rotacionados quando usados.

Verificações comuns

Um callback rejeitado geralmente difere da URI registrada em esquema, host, porta, caminho, capitalização ou barra final.
invalid_request antes do consentimento significa que PKCE S256, o challenge ou o state está ausente ou inválido.
invalid_grant geralmente significa que um código ou um token de atualização rotacionado foi reutilizado, ou que o callback ou o verifier foi alterado.
Após um 401, atualize uma vez; se a atualização falhar, peça ao usuário para reconectar. Um 403 significa que o token não tem o escopo necessário.

Veja o contrato OpenAPI completo e o guia detalhado de integração de Apps Conectadas.