Uptime serviços Zydon

App Studio

Guia Completo de Integração OAuth Zydon

Este guia detalha como implementar a integração OAuth com a plataforma Zydon, permitindo que seus clientes autorizem o acesso aos dados da conta Zydon deles através do seu plugin/aplicação.

Pré-requisitos

Antes de começar, garanta que seu plugin já está registrado na plataforma Zydon. Com o registro, você receberá três informações essenciais:

  1. client_id: (Plugin ID).

  2. access_key: Sua chave secreta.

  3. URLs de Callback: Os endereços para onde o cliente será enviado após a autorização.

🚀 Fluxo OAuth Completo

Etapa 1: Redirecionamento para Autorização

Redirecione seu cliente para a URL de autorização do Zydon:

https://admin.zydon.com.br/oauth/authorize?client_id={PLUGIN_ID}&redirect_uri={CALLBACK_URL}&state={STATE}

Parâmetros Obrigatórios:

  • client_id: ID do seu plugin (UUID)

  • redirect_uri: URL de callback autorizada do seu sistema

  • state: Valor aleatório para proteção CSRF (recomendado)

Exemplo:

https://admin.zydon.com.br/oauth/authorize?client_id=123e4567-e89b-12d3-a456-426614174000&redirect_uri=https://meuapp.com/callback&state=xyz123

Etapa 2: Autorização do Cliente

O cliente será direcionado para a tela de autorização do Zydon onde:

  1. Visualizará as permissões solicitadas

  2. Decidirá se autoriza ou não o acesso

  3. Seu plugin será instalado automaticamente (se ainda não estiver)

Etapa 3: Callback com Código de Autorização

Após a autorização, o cliente será redirecionado para sua URL de callback:

Sucesso:

https://meuapp.com/callback?code={AUTHORIZATION_CODE}&state={STATE}

Erro:

https://meuapp.com/callback?error={ERROR_CODE}&state={STATE}

Códigos de Erro Possíveis:

  • invalid_client: Plugin não encontrado ou URL de callback não autorizada

  • server_error: Erro interno durante a instalação/autorização

Etapa 4: Troca do Código por Token de Acesso

Com o código de autorização recebido, faça uma requisição para obter o token de acesso:

Endpoint:

POST https://api.zydon.com.br/appcenter/oauth/token

Headers:

Content-Type: application/x-www-form-urlencoded
Authorization: Basic {BASE64_ENCODED_CREDENTIALS}

Credenciais Basic Auth:

Base64({PLUGIN_ID}:{ACCESS_KEY})

Body (form-urlencoded):

grant_type=authorization_code
code={AUTHORIZATION_CODE}
redirect_uri={CALLBACK_URL}

Exemplo de Requisição:

curl -X POST https://api.zydon.com.br/appcenter/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwOmFiY2RlZmdoLWlqa2wtbW5vcC1xcnN0LXV2d3h5ejEyMzQ1Ng==" \
  -d "grant_type=authorization_code&code=987fcdeb-51a2-43d7-b890-123456789abc&redirect_uri=https://meuapp.com/callback"

Resposta de Sucesso (200):

{
  "access_key_code": "987fcdeb-51a2-43d7-b890-123456789abc",
  "access_key_token": "fedcba98-7654-3210-fedc-ba9876543210"
}

🔑 Usando as Credenciais de Acesso

Após obter as credenciais, você pode usar o access_key_code e access_key_token para fazer chamadas autenticadas às APIs do Zydon em nome do cliente.

Autenticação nas APIs:

Authorization: Bearer {ACCESS_KEY_TOKEN}
X-Access-Key-Code: {ACCESS_KEY_CODE}

⚠️ Tratamento de Erros

Erros na Autorização:

  • 404: Plugin não encontrado

  • 400: Parâmetros inválidos

  • 401: Não autorizado

Erros na Troca de Token:

  • 400: grant_type inválido (deve ser authorization_code)

  • 401: Credenciais Basic Auth inválidas

  • 404: Código de autorização não encontrado ou expirado

🛡️ Segurança

Boas Práticas:

  1. Sempre use HTTPS em suas URLs de callback

  2. Valide o parâmetro state para prevenir ataques CSRF

  3. Mantenha o access_key seguro - nunca exponha no frontend

  4. Configure apenas URLs de callback confiáveis no seu plugin

  5. Implemente timeout para códigos de autorização

Validações Implementadas:

  • URLs de callback devem estar pré-autorizadas

  • Códigos de autorização têm tempo de vida limitado

  • Access key é validada em cada requisição

📊 Fluxo Técnico Resumido

💡 Exemplo Prático de Implementação

1. Iniciando o Fluxo (Backend da sua aplicação):

// Gerar state aleatório para CSRF protection
const state = crypto.randomUUID();
// Salvar state na sessão/cache para validação posterior

const authUrl = `https://admin.zydon.com.br/oauth/authorize?` +
  `client_id=${PLUGIN_ID}&` +
  `redirect_uri=${encodeURIComponent(CALLBACK_URL)}&` +
  `state=${state}`;

// Redirecionar cliente para authUrl
res.redirect(authUrl);

2. Tratando o Callback:

app.get('/callback', async (req, res) => {
  const { code, state, error } = req.query;
  
  // Validar state para CSRF protection
  if (state !== getStoredState()) {
    return res.status(400).send('Invalid state');
  }
  
  if (error) {
    return res.status(400).send(`Authorization error: ${error}`);
  }
  
  try {
    // Trocar código por token
    const credentials = await exchangeCodeForToken(code);
    
    // Salvar credenciais do cliente
    await saveClientCredentials(clientId, credentials);
    
    res.send('Autorização realizada com sucesso!');
  } catch (err) {
    res.status(500).send('Erro ao obter token de acesso');
  }
});

3. Trocando Código por Token:

async function exchangeCodeForToken(code) {
  const credentials = Buffer.from(`${PLUGIN_ID}:${ACCESS_KEY}`).toString('base64');
  
  const response = await fetch('https://api.zydon.com.br/appcenter/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${credentials}`
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: code,
      redirect_uri: CALLBACK_URL
    })
  });
  
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }
  
  return await response.json();
}

4. Usando as Credenciais para Acessar APIs:

async function callZydonAPI(endpoint, accessKeyCode, accessKeyToken) {
  const response = await fetch(`https://api.zydon.com.br${endpoint}`, {
    headers: {
      'Authorization': `Bearer ${accessKeyToken}`,
      'X-Access-Key-Code': accessKeyCode,
      'Content-Type': 'application/json'
    }
  });
  
  if (!response.ok) {
    throw new Error(`API Error: ${response.status}`);
  }
  
  return await response.json();
}

🎯 URLs de Referência

  • Frontend (Autorização): https://admin.zydon.com.br/oauth/authorize

  • Backend API (Token): https://api.zydon.com.br/appcenter/oauth/token

  • Backend APIs (Dados): https://api.zydon.com.br/*

📋 Checklist de Implementação

Atualizado