Control API - ambientes
Use FoxIDs Control API para listar, criar, configurar e excluir ambientes em um tenant. Um ambiente é chamado de track em Control API rotas e esquemas.
Antes de chamar essas operações, configure Control API autenticação e direitos de acesso. Swagger continua sendo a referência exata para todas as propriedades do ambiente, regras de validação e esquemas de resposta:
Base de endpoint
A administração do ambiente é executada por meio do ambiente master do tenant. Os exemplos usam FoxIDs Cloud:
https://control.foxids.com/api/{tenant_name}/master
Substitua {tenant_name} pelo nome técnico de tenant. Altere o host para uma implantação auto-hospedada. Envie o token de acesso Control API no cabeçalho Authorization: Bearer {access_token}.
As operações de ambiente requerem o tenant correspondente ou o direito de acesso ao ambiente. Os ambientes retornados pelas operações de lista são limitados àqueles que o chamador pode acessar. Use a Control API hierarquia de direitos de acesso para conceder apenas a operação read, create, update ou delete necessária.
Operações ambientais
As operações de ambiente são agrupadas em tenant tracks em Swagger.
| Operação | Ponto final | Propósito |
|---|---|---|
| Lista | GET /!tracks |
Liste ambientes acessíveis com filtragem e paginação opcionais. |
| Pegar | GET /!track?name={name} |
Obtenha a configuração completa para um ambiente. |
| Criar | POST /!track |
Crie um ambiente e seu método de autenticação de Login padrão. |
| Atualizar | PUT /!track |
Substitua a configuração do ambiente editável. |
| Excluir | DELETE /!track?name={name} |
Exclua permanentemente um ambiente e seus dados. |
Anexe cada endpoint à base de endpoint.
Liste e identifique ambientes
GET /!tracks aceita filterName e paginationToken. O filtro corresponde ao name técnico ou ao displayName, independentemente do caso.
A resposta contém uma coleção data e um paginationToken opaco. Para ler a próxima página, repita a mesma solicitação com o token retornado e o mesmo filtro. Continue até que a resposta não contenha mais um token. Não interprete ou modifique o token.
O name técnico identifica o ambiente em Control API URLs e nas operações subsequentes de obtenção, atualização e exclusão. Trate-o como uma chave de automação estável. Use displayName para texto apresentado aos administradores.
Crie um ambiente
Os nomes dos ambientes estão em letras minúsculas. Forneça um name quando uma integração exigir um URL previsível ou omita-o e deixe que FoxIDs gere um nome exclusivo. Uma solicitação deve conter um nome ou um nome de exibição.
A criação de um ambiente também cria o método de autenticação de Login padrão. Outros aplicativos, métodos de autenticação, usuários, chaves e recursos de ambiente são configurados separadamente após a criação.
O plano tenant pode limitar o número de ambientes. Uma solicitação de criação pode, portanto, falhar quando o limite for atingido. As operações simultâneas de criação limitadas pelo plano podem retornar 423 Locked; tente novamente após um pequeno atraso.
Atualizar configurações de ambiente
PUT /!track é uma atualização completa, não um patch. Primeiro obtenha o ambiente atual, preserve todas as propriedades que devem permanecer inalteradas, aplique as alterações pretendidas e envie a representação editável completa.
O name técnico seleciona o ambiente e não é renomeado por uma atualização. As configurações editáveis incluem exibição e detalhes da empresa, vida útil da sequência, comportamento de mapeamento de declarações, proteção contra falhas de login, políticas de senha, senha externa e integração de diretório e domínios iframe permitidos. Alguns recursos relacionados, incluindo SMS, e-mail, mapeamentos de declarações, textos, chaves e certificados, têm pontos finais dedicados e não são substituídos através da operação do ambiente.
As configurações atualizadas são usadas por solicitações subsequentes após FoxIDs invalidar o cache de configuração do ambiente.
Excluir um ambiente
A exclusão de um ambiente é uma operação irreversível e em cascata. Ele remove a configuração do ambiente e todos os dados com escopo definido para esse ambiente, incluindo seus aplicativos, métodos de autenticação, usuários, sessões, concessões, chaves e outros recursos. Links de outros ambientes para o ambiente excluído também são removidos.
Não use a exclusão de ambiente como forma de limpar recursos selecionados. Exclua ou atualize esses recursos individualmente quando o ambiente precisar permanecer disponível. Antes de excluir um ambiente, interrompa o tráfego para ele, exporte qualquer configuração ou dados que devam ser retidos e verifique o nome técnico na solicitação.
Orientação de automação
- Mantenha os nomes técnicos estáveis e armazene-os separadamente dos nomes de exibição.
- Use a paginação de lista mesmo quando um tenant tiver atualmente apenas alguns ambientes.
- Use um fluxo de trabalho get-modify-put para evitar a redefinição acidental de configurações adicionadas em uma versão mais recente do FoxIDs.
- Crie recursos dependentes somente depois que a solicitação de criação do ambiente for bem-sucedida.
- Trate a exclusão como uma operação de desmontagem permanente e exija uma confirmação explícita nas ferramentas administrativas.
- Espere que solicitações de criação, atualização e exclusão apareçam no log de auditoria do Controle. As operações de leitura não são gravadas como eventos de auditoria.
Respostas de erros comuns
400 Bad Requestquando os dados ou o nome do ambiente são inválidos, um nome reservado é usado ou um limite do plano é atingido.401 Unauthorizedquando o token de acesso está ausente ou é inválido.403 Forbiddenquando o chamador não possui o direito de acesso necessário.404 Not Foundquando o ambiente selecionado não existe.409 Conflictquando já existe um ambiente com o mesmo nome técnico.423 Lockedquando uma operação de criação limitada ao plano é temporariamente bloqueada.
Use o corpo da resposta para detalhes de validação e Swagger UI para as respostas declaradas por cada operação.