DriveB

01. Autenticação

Este módulo fornece os mecanismos necessários para autenticar usuários e aplicações na plataforma. Através dele, é possível obter tokens de acesso, validar permissões e garantir a segurança das requisições realizadas via API.

As APIs do DriveB utilizam o protocolo de autenticação OAuth 2.0 com tokens do tipo Bearer.

Fundamentos e Credenciais

Antes de realizar chamadas aos endpoints seguros, é necessário compreender as premissas de segurança e obter os identificadores de acesso.

Conceitos-Chave

  • client_id: Identificador exclusivo da sua aplicação fornecido pela equipe DriveB.

  • client_secret: Chave privada e confidencial de segurança utilizada para assinar as requisições de autenticação.

  • Bearer Token: Token de acesso seguro temporário que deve ser enviado no cabeçalho (Header) de todas as requisições subsequentes.

Tabela de Parâmetros de Autenticação

Parâmetro Tipo Obrigatório Descrição
client_id string Sim Identificador único do cliente corporativo ou da integração.
client_secret string Sim Chave de segurança privada associada ao client_id.
grant_type string Sim Método de concessão de autorização. Deve ser preenchido como client_credentials.

Fluxo de Trabalho (Workflow)

O fluxo para consumo seguro da API segue uma sequência lógica obrigatória:

  1. Geração do Token: A aplicação cliente envia suas credenciais (client_id e client_secret) com o grant_type configurado para o servidor de identidade no endpoint de autenticação.

  2. Recebimento e Armazenamento: O servidor valida as credenciais e retorna um token de acesso temporário (access_token) junto com o tempo de expiração (expires_in).

  3. Consumo Seguro: A aplicação utiliza o token gerado em todas as chamadas de API subsequentes, adicionando-o ao cabeçalho da requisição da seguinte forma:

Authorization: Bearer <access_token>

Referência de Endpoints

Gerar Token de Acesso

Utilize este endpoint para obter seu token ativo e iniciar as chamadas seguras nos demais módulos da API.

Exemplo de Payload de Envio (Request Body):

{
"grant_type": "client_credentials",
"client_id": "xxxx",
"client_secret": "xxxx"
}

Resposta de Exemplo (Response Body) - Status 200 OK:

{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 3600,
"refresh_expires_in": 1800,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "profile email"
}

Erros e Resolução de Problemas

Garanta o tratamento adequado das respostas de erro em sua aplicação utilizando as recomendações abaixo:

Códigos de Status HTTP Comuns

Status HTTP Causa Provável Ação Recomendada
200 OK Credenciais corretas e token gerado com sucesso. Prossiga para o consumo dos demais endpoints anexando o token gerado.
400 Bad Request Parâmetros ou campos inválidos no corpo da requisição (ex: grant_type incorreto). Verifique o payload enviado e confirme se o corpo está formatado como JSON correto.
401 Unauthorized client_id ou client_secret inválidos ou expirados. Revise as credenciais fornecidas pela equipe DriveB e certifique-se de que não há espaços em branco.
403 Forbidden Cliente sem permissão para acessar o escopo solicitado. Entre em contato com o suporte para verificar se os escopos do seu cliente estão ativos.
500 Internal Error Erro imprevisto no servidor de autenticação. Aguarde alguns minutos e tente novamente (política de retry exponencial).

Dicas de Resolução de Problemas

  • Expiração do Token: O token tem um tempo de vida especificado no campo expires_in (geralmente em segundos, como 3600 para 1 hora). Programe sua aplicação para renovar o token de forma automatizada e transparente antes que ele expire, evitando falhas de autenticação (401 Unauthorized) no meio de processos integrados.

  • Segurança de Credenciais: Nunca exponha o client_secret em ambientes públicos ou aplicações client-side (como Javascript puro no navegador). Guarde as credenciais de forma segura em variáveis de ambiente em seu backend.