Primeiros passos com a API

A API cobre 510 operações — praticamente tudo que a interface faz. Esta página é o suficiente para a primeira requisição funcionar.

Autenticação: dois caminhos

Caminho	Para quê
Token bearer de integração	Servidor a servidor. É o caminho recomendado.
Cookie de sessão	O que a interface web usa. Serve para testar rapidamente copiando o cookie de uma sessão aberta.

Há ainda três esquemas específicos, declarados na especificação: dois do agente de endpoint (token permanente e token de instalação) e um para serviço externo de código de uso único.

As duas rotas que você procura

São as duas de que se precisa para instalar o cliente Windows, e nenhuma delas se chama o que a memória sugere. Elas ficam em pastas diferentes ao importar a especificação num cliente de API, porque a segunda pertence ao módulo de Manutenção, não ao de autenticação:

O que você quer	Rota	Pasta / etiqueta	Nome do pedido
Bearer para consumir a API	`POST /manager-api/auth/api-token`	Authentication	Generate a Bearer token (username + password) — start here
Token de instalação do cliente	`POST /manager-api/agent-control/enrollment-tokens`	Endpoint Maintenance	Generate an Agent enrollment token (client install)

Existe também POST /manager-api/api-tokens — etiqueta api-tokens, nome Create api token. Não é essa. A diferença não aparece no nome:

	`/manager-api/auth/api-token`	`/manager-api/api-tokens`
Exige estar autenticado antes	Não	Sim
Permissão	Nenhuma	`settings.api` em edição — que é exclusiva de super administrador
Corpo	`username` + `password`	`name`, `userId`, `expiresInHours`
Para quê	Obter o primeiro bearer, do zero	Gerenciar tokens de dentro da interface

Chamar /manager-api/api-tokens sem sessão devolve 401, e o sintoma é indistinguível de credencial errada. Se a autenticação “parou de funcionar” depois de uma atualização da especificação, é quase sempre esta troca: o caminho no singular, sob /auth/, é o que aceita usuário e senha.

A diferença de estilo dos nomes também confunde e vale explicar: as etiquetas em maiúsculas com espaço (Authentication, Endpoint Maintenance) são das operações escritas à mão; as em minúsculas com hífen (api-tokens) são geradas do código. Etiqueta feia é sinal de operação com corpo genérico — não de operação menos real.

1. Obter um token de integração

Não exige sessão prévia. Aceita conta local e conta de diretório.

POST /manager-api/auth/api-token
Content-Type: application/json

{
  "username": "integracao.exemplo",
  "password": "…",
  "name": "Integração de exemplo",
  "expiresInHours": 720
}

Responde 201 com access_token. Use em todas as demais chamadas:

Authorization: Bearer <access_token>

curl -sS -X POST https://openscale.suaempresa.com.br/manager-api/auth/api-token \
  -H 'Content-Type: application/json' \
  -d '{"username":"integracao.exemplo","password":"…","name":"Integração","expiresInHours":720}'

Confira que funcionou:

curl -sS https://openscale.suaempresa.com.br/manager-api/auth/me \
  -H "Authorization: Bearer $TOKEN"

2. Token de instalação de agente

Precisa do token acima e da permissão ativos.computadores em nível de edição.

POST /manager-api/agent-control/enrollment-tokens
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "label": "Lote de agosto",
  "max_uses": 50,
  "expires_at": "2026-09-01T00:00:00.000Z"
}

Responde 201 com o token, prefixo ose_enroll_, exibido uma única vez. Um token serve para max_uses máquinas; o padrão é 1, então para frota informe o número.

Este é o token que o instalador do cliente Windows consome.

3. O que a máquina faz com ele

Para referência — este passo é do instalador, não seu:

POST /api/v1/agents/enroll
x-openscale-enrollment-token: ose_enroll_…

{ "agent_id": "…", "hostname": "…", "platform": "windows" }

Responde com o token permanente daquela máquina, o identificador do agente e as credenciais de armazenamento que ela grava na própria configuração. O token de instalação não é mais usado.

Convenções

Prefixos. /manager-api/… é a API da aplicação; /api/v1/agents/… é a dos agentes de endpoint. Não são intercambiáveis, e cada operação declara a sua guarda.

Permissões. A API aplica o mesmo controle de acesso da interface, incluindo o piso que restringe administração da plataforma a super administrador. Um token não contorna permissão: ele herda a da conta. Ver Permissões e papéis.

Escopo por setor. Onde o módulo é escopável, a resposta é filtrada pelo escopo da conta. Uma integração sem escopo recebe lista vazia — não erro.

Recusas que parecem defeito e não são

Resposta	Significado
`400 missing-credentials`	O corpo de `/auth/api-token` precisa de `username` e `password`.
`409 already-rated`	A avaliação de satisfação é definitiva. A resposta traz a avaliação que vale.
`409 ticket-closed`	Escrita em chamado fechado ou cancelado.
`422 sector-not-found`	Setor inexistente. A resposta traz a lista dos válidos.
`401` no registro de agente	Token de instalação ausente, expirado ou com usos esgotados.

Campos que a especificação não detalha

351 das 510 operações são geradas do código: caminho, método, parâmetros e guarda de acesso são exatos, mas o corpo é genérico. Três campos úteis que ficariam invisíveis:

Rota	Campo	Efeito
`POST /tickets/{id}/events`	`resolve: true`	Responde e resolve na mesma requisição. Só vale para quem gerencia o setor, e não vale em nota interna.
`POST /tickets/{id}/satisfaction`	—	A nota é definitiva; reenviar devolve `409` com a avaliação que vale.
`PATCH /ticket-settings`	`sla`	Expediente (dias, início, fim, feriados, fuso), pausa em pendente, escalonamento e fechamento automático. Recusa `400` se o fim não for depois do início, ou se o expediente ficar sem dia.

Próximo passo

Especificação OpenAPI — baixar o arquivo e consumi-lo em um cliente.