Visão Geral da API da Dadosfera

A API da Dadosfera é a camada programática da plataforma. Ela permite integrar sistemas externos, automatizar operações e gerenciar recursos como pipelines, conexões, arquivos, tabelas, datasets, ativos de catálogo, clientes e credenciais de acesso.

Na prática, ela atende tanto cenários de uso interativo quanto integrações entre sistemas, permitindo que aplicações e serviços executem ações na plataforma de forma controlada e segura.

O que a API cobre

Hoje, a documentação da API reúne recursos para:

• autenticação e renovação de token
• criação, execução, monitoramento e manutenção de pipelines
• gerenciamento de conexões e integrações com OAuth
• operações com arquivos, tabelas e datasets no storage
• busca e manutenção de ativos de dados no catálogo
• operações relacionadas a clientes e administração da plataforma
• criação e gestão de API keys para acesso programático
• verificação de saúde e disponibilidade de serviços

Novo fluxo de autenticação

O fluxo de autenticação foi estruturado para atender tanto usuários humanos quanto integrações automatizadas.

Autenticação de usuário

O login principal é feito com username e password. Quando a autenticação multifator estiver habilitada, também é necessário enviar o código totp.

Após o login com sucesso, a resposta retorna:

• accessToken: token usado para autenticar as requisições à API
• refreshToken: token usado para gerar um novo accessToken
• customer: informações do ambiente, como id, nome e módulos disponíveis
• user: informações do usuário autenticado

Pelos tempos documentados atualmente no Maestro:

• accessToken: expira em 30 minutos
• refreshToken: expira em 24 horas

Renovação do token

Quando o accessToken expira, o cliente pode chamar a rota de renovação usando o refreshToken atual e o customerName retornado no login. Esse modelo evita a necessidade de repetir o login completo a cada expiração do token de curta duração.

API Keys

Para integrações backend e automações, a plataforma também disponibiliza API keys com permissões explícitas. Esse é o caminho mais indicado para cenários server-to-server, nos quais não faz sentido depender de uma sessão de usuário interativa.

As API keys:

• são criadas com um conjunto definido de permissões
• têm o valor completo exibido apenas no momento da criação
• devem ser armazenadas com segurança
• podem ser rotacionadas por meio da criação de uma nova chave e remoção da anterior

Boas práticas

• Use autenticação por usuário quando houver contexto de sessão e ações realizadas em nome de um usuário autenticado.
• Use API keys para integrações automatizadas e serviços internos.
• Trate accessToken como credencial de curta duração.
• Armazene refreshToken e API keys em segredo seguro.
• Revise as permissões antes de liberar acesso para produção.

Próximos passos

Depois desta visão geral, consulte a documentação de referência para ver os endpoints específicos de autenticação, pipelines, storage, catálogo e demais domínios da plataforma.