> For the complete documentation index, see [llms.txt](https://wiki.datadike.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.datadike.com/pt/pam/reference/api.md).

# API

Onde fica a especificação da API, as três formas de um cliente se autenticar, as convenções que todos os endpoints compartilham e o que cada família cobre.

## O que é isto e quando usar

A solução expõe uma API REST sobre HTTPS. O próprio console é cliente dela: toda tela que você usa chama os mesmos endpoints que um sistema externo chamaria, e é por isso que tudo o que o console faz pode ser feito programaticamente.

Use a API para cadastrar ativos a partir de um CMDB, recuperar uma credencial dentro de uma esteira, exportar registros de auditoria para um data warehouse ou conduzir admissão e desligamento a partir de um sistema de identidade.

## Onde fica a especificação

Dois endereços na sua própria instância, ambos gerados a partir da versão que está de fato em execução:

| Endereço                                   | O que é                   | Para que serve                               |
| ------------------------------------------ | ------------------------- | -------------------------------------------- |
| `https://<sua-instancia>/api/docs`         | Documentação interativa   | Navegar pelos endpoints e testar uma chamada |
| `https://<sua-instancia>/api/swagger.json` | Especificação OpenAPI 2.0 | Gerar um cliente em qualquer linguagem       |

{% hint style="info" %}
Leia a especificação da **sua própria instância**, e não de qualquer lista anotada em outro lugar. Ela corresponde à versão com a qual você está integrando, coisa que uma página de wiki não tem como garantir.
{% endhint %}

Todos os endpoints ficam sob o prefixo `/api/v1/`, e a API responde somente por HTTPS. Um cliente que não consegue validar o certificado da instância falha na camada de transporte antes que a autenticação importe, então um certificado autoassinado precisa ser confiado pela máquina que chama.

## Como um cliente se autentica

Não existe acesso anônimo. Três mecanismos estão disponíveis, e eles carregam identidades diferentes.

| Mecanismo                                  | Identidade            | Como a credencial é obtida                                    |
| ------------------------------------------ | --------------------- | ------------------------------------------------------------- |
| **Assinatura por chave de acesso**         | Um usuário do console | **Perfil › Chave de Acesso**, que emite um ID e um segredo    |
| **Assinatura por aplicação de integração** | Uma aplicação         | Cadastrada por um administrador, que emite um ID e um segredo |
| **Token Bearer**                           | Um usuário do console | `POST /api/v1/authentication/auth/` com usuário e senha       |

### Assinando uma requisição

Os dois mecanismos de assinatura usam HTTP Signature com HMAC-SHA256. O cliente monta uma string de assinatura a partir do alvo da requisição e da data, assina com o seu segredo e envia o resultado no cabeçalho `Authorization`.

```
(request-target): get /api/v1/assets/hosts/?limit=10
date: Wed, 23 Sep 2026 20:44:35 GMT
```

```
Authorization: Signature keyId="<id>",algorithm="hmac-sha256",
               headers="(request-target) date",signature="<base64>"
Date: Wed, 23 Sep 2026 20:44:35 GMT
```

Três detalhes decidem se a chamada funciona:

* **A query string faz parte da string de assinatura.** Assine o alvo da requisição exatamente como ele será enviado, com os parâmetros e na mesma ordem.
* **A data precisa estar em RFC 7231, em inglês, em GMT.** Um cliente rodando em máquina com idioma diferente do inglês, que formate a data no idioma local, produz um cabeçalho que o servidor rejeita. Essa é a falha de integração mais comum, e ela só aparece fora de ambientes em inglês.
* **Uma aplicação de integração acrescenta `X-Source: datadike-pam`.** É esse cabeçalho que distingue uma aplicação da chave de acesso de um usuário, e sem ele a requisição é interpretada como a segunda.

### Token Bearer

Um token obtido no endpoint de login é enviado como `Authorization: Bearer <token>`. Ele carrega as permissões do usuário para quem foi emitido e tem vida curta, o que o torna adequado a um script interativo e inadequado a uma rotina desassistida. Para qualquer coisa que rode sem uma pessoa presente, prefira a assinatura.

{% hint style="warning" %}
Uma chave de acesso carrega todas as permissões do usuário dono dela, portanto é tão poderosa quanto o papel dessa pessoa. Já uma aplicação de integração é limitada duas vezes: às contas que pode ler e aos endereços de origem de onde pode chamar. **Para acesso de máquina, prefira uma aplicação de integração.**
{% endhint %}

### Clientes prontos

O produto entrega um cliente funcional e a respectiva documentação para seis linguagens, servidos pela própria instância na aba **SDKs** da aplicação de integração. Cada um implementa a assinatura descrita acima.

| Linguagem  | Dependências                        |
| ---------- | ----------------------------------- |
| Python     | `requests`, `httpsig`               |
| Java       | Nenhuma. Apenas a biblioteca padrão |
| Go         | Nenhuma. Apenas a biblioteca padrão |
| Node.js    | `axios`                             |
| PowerShell | Nenhuma. Apenas cmdlets nativos     |
| curl       | Nenhuma                             |

## Convenções que todos os endpoints compartilham

### Paginação

Coleções são paginadas com `limit` e `offset`, e respondem com um envelope consistente:

```json
{ "count": 412, "next": "...", "previous": null, "results": [] }
```

### Busca, ordenação e filtro

| Parâmetro       | O que faz                                                             |
| --------------- | --------------------------------------------------------------------- |
| `search`        | Busca textual livre nos campos pesquisáveis do recurso                |
| `order`         | Campo para ordenar. Prefixe com `-` para inverter                     |
| *nome do campo* | Filtro por valor exato. Quais campos são filtráveis varia por recurso |

### Descobrindo os campos de um recurso

Uma requisição `OPTIONS` a uma coleção devolve os metadados dos campos do recurso: nomes, tipos, se cada um é obrigatório e as opções disponíveis. É o caminho mais rápido para conhecer um payload sem ler a especificação inteira, e reflete as suas próprias permissões.

### Formatos de exportação

Coleções são renderizadas em JSON, CSV ou XLSX. Acrescente `format=csv` ou `format=xlsx` a um `GET`, e a resposta traz uma linha de cabeçalho com os mesmos nomes de coluna que o console exporta.

### Idioma

As respostas honram o cabeçalho `Accept-Language` e informam o que usaram em `Content-Language`. Mensagens de erro, rótulos de campo e textos de validação voltam traduzidos.

| Enviado | Recebido                                               |
| ------- | ------------------------------------------------------ |
| `en`    | `Authentication credentials were not provided.`        |
| `pt-br` | `As credenciais de autenticação não foram fornecidas.` |
| `es`    | `Las credenciales de autenticación no se proveyeron.`  |
| `fr`    | `Informations d'authentification non fournies.`        |

Para uma chamada autenticada como usuário do console, a preferência de idioma desse usuário prevalece sobre o cabeçalho.

### Organizações

Uma instância pode abrigar várias organizações, e a maioria dos recursos pertence a uma delas. As requisições informam a organização no cabeçalho `X-PAM-ORG`. Um cliente que o omite opera na organização padrão, o que é causa frequente de uma chamada ter sucesso e não devolver nada.

## Famílias de endpoints

Todas as famílias abaixo estão cobertas pela especificação da sua instância. A contagem de operações mede superfície, não importância.

| Família                | Prefixo            | Operações | O que cobre                                                                              |
| ---------------------- | ------------------ | --------- | ---------------------------------------------------------------------------------------- |
| Sessões e conectores   | `/terminal/`       | 249       | Sessões ao vivo, gravações, endpoints de conexão, applets, hosts publicadores            |
| Ativos                 | `/assets/`         | 229       | Hosts, bancos de dados, dispositivos, nuvem, plataformas, nós, zonas, descoberta         |
| Contas                 | `/accounts/`       | 159       | Contas gerenciadas, modelos, rotação, descoberta, backup, aplicações de integração       |
| Autenticação           | `/authentication/` | 100       | Login, MFA, chaves de acesso, chaves SSH, passkeys, tokens de conexão                    |
| Solicitações           | `/tickets/`        | 96        | Pedidos de acesso, fluxos de aprovação, aprovadores                                      |
| Autorizações           | `/perms/`          | 77        | Quem pode alcançar qual ativo com qual conta                                             |
| Papéis e permissões    | `/rbac/`           | 75        | Papéis, vínculos de papel, catálogo de permissões                                        |
| Usuários               | `/users/`          | 70        | Usuários, grupos, sincronização com diretório                                            |
| Automação              | `/ops/`            | 64        | Trabalhos, comandos ad hoc, playbooks, histórico de execução                             |
| Controle de acesso     | `/acls/`           | 58        | Filtros de comando, regras de login, regras de método de conexão                         |
| Gateways               | `/brokers/`        | 37        | Gateways reversos e os alvos alcançáveis por eles                                        |
| Etiquetas              | `/labels/`         | 34        | Etiquetas e o que as carrega                                                             |
| Auditoria              | `/audits/`         | 28        | Registros de login, logs de operação, retiradas de credencial, transferências de arquivo |
| Notificações           | `/notifications/`  | 26        | Canais, assinaturas, modelos de mensagem                                                 |
| Configurações          | `/settings/`       | 25        | Configuração do sistema                                                                  |
| Análise comportamental | `/ueba/`           | 20        | Achados comportamentais e suas regras                                                    |
| Relatórios             | `/reports/`        | 19        | Definições de relatório, execuções, downloads                                            |
| Cofre                  | `/vault/`          | 16        | Credenciais guardadas e compartilhadas manualmente, em pastas                            |
| Organizações           | `/orgs/`           | 12        | Tenants e seus membros                                                                   |

## Erros

As falhas respondem com um corpo JSON que traz um `detail` legível por pessoas e um `code` estável:

```json
{ "detail": "Authentication credentials were not provided.", "code": "not_authenticated" }
```

| Status | Causa habitual                                                                       |
| ------ | ------------------------------------------------------------------------------------ |
| 400    | Um payload que não passou na validação. O corpo nomeia os campos com problema        |
| 401    | Sem credencial, token expirado, ou assinatura que o servidor não conseguiu verificar |
| 403    | Uma identidade válida, sem permissão para este recurso                               |
| 404    | O recurso não existe, ou pertence a outra organização                                |

Trate o `code`, e não o `detail`, porque o `detail` é traduzido e o `code` não.

## Como verificar que você alcança a API

Três checagens, na ordem que encontra problemas mais rápido:

1. **Chame o endpoint de saúde.** Ele não exige credencial, o que o torna a prova mais rápida de que rede, nome de host e TLS estão funcionando:

   ```bash
   curl -s "https://<sua-instancia>/api/health/"
   ```

   Uma instância saudável responde com `"status": true`, junto do estado do banco de dados e do cache.
2. **Chame uma coleção com a sua credencial** e confirme que o envelope volta. `GET /api/v1/users/users/?limit=1` é uma escolha segura, e um 401 aqui, com a instância saudável, aponta para a credencial e não para a conexão.
3. **Repita a chamada a partir da máquina que vai rodar a integração.** Os endereços de origem permitidos de uma aplicação são aplicados, então uma chamada que funciona na sua estação pode ser recusada no servidor que precisa dela.

## Erros comuns

| Sintoma                                                   | Causa                                                                                           | Correção                                                                    |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| 401 com uma assinatura que parece correta                 | A data foi formatada no idioma da máquina, ou o relógio está fora de hora                       | Formate a data em inglês, em GMT, e mantenha o relógio do host sincronizado |
| 401 apenas quando há query string                         | A assinatura cobriu o caminho sem os parâmetros                                                 | Assine o alvo da requisição exatamente como ele é enviado                   |
| Uma aplicação de integração não se autentica como ninguém | Falta o `X-Source: datadike-pam`                                                                | Acrescente o cabeçalho                                                      |
| A chamada tem sucesso mas a coleção volta vazia           | O cliente está operando na organização padrão                                                   | Envie `X-PAM-ORG` com a organização pretendida                              |
| A chamada funciona na sua estação e falha no servidor     | Os endereços de origem permitidos da aplicação não incluem esse servidor                        | Acrescente o endereço à aplicação                                           |
| 403 com uma credencial que funciona                       | O usuário ou a aplicação não tem permissão para aquele recurso                                  | Verifique o papel, ou o escopo de contas da aplicação                       |
| Não se consegue alcançar `/api/docs`                      | A instância está sendo endereçada por um nome que o cliente não resolve, ou o TLS está falhando | Use o mesmo endereço de **Configurações do Sistema › Geral › URL do site**  |

## Páginas relacionadas

* [Acesso aplicação para aplicação](https://wiki.datadike.com/pt/pam/administration/integrations/application-to-application.md), como recuperar uma credencial sem uma pessoa
* [O cofre de credenciais](https://wiki.datadike.com/pt/pam/administration/accounts/vault.md), de onde esses endpoints leem
* [Trilha de auditoria](https://wiki.datadike.com/pt/pam/administration/audit/audit-trail.md), onde as chamadas de API ficam registradas
* [Campos de configuração](https://wiki.datadike.com/pt/pam/reference/configuration-fields.md), a URL do site que os clientes devem endereçar
