Administração Control API - tenant

FoxIDs tem superfícies Control API separadas para operadores de implantação que administram tenants e para um tenant que administra sua própria conta. Use as operações do operador para provisionamento tenant e administraçãotenant cruzada. Use as operações de autoatendimento quando uma integração precisar ser confinada ao seu próprio tenant.

Antes de chamar essas operações, configure Control API autenticação e direitos de acesso. Swagger continua sendo a referência exata para tenant propriedades, planos e opções de pagamento, regras de validação e esquemas de resposta:

API superfícies

Operador de implantação

As operações do operador são chamadas em master tenant:

https://control.foxids.com/api/master/master

Operação	Ponto final	Propósito
Lista	`GET /!tenants`	Lista não master tenants com filtros e paginação opcionais.
Pegar	`GET /!tenant?name={name}`	Leia o recurso de administração de um tenant.
Criar	`POST /!tenant`	Provisione um tenant, um administrador inicial e recursos padrão.
Atualizar	`PUT /!tenant`	Substitua as propriedades tenant editáveis gerenciadas pelo operador.
Excluir	`DELETE /!tenant?name={name}`	Exclua permanentemente um tenant e todos os dados de tenant.

Essas operações exigem direitos de acesso master-tenant. Eles são destinados à administração de implementação confiável e SaaS serviços de provisionamento.

Tenant autoatendimento

Um tenant chama suas próprias operações por meio do ambiente master:

https://control.foxids.com/api/{tenant_name}/master

Operação	Ponto final	Propósito
Pegar	`GET /!mytenant`	Leia a conta tenant do chamador e as configurações disponíveis.
Atualizar	`PUT /!mytenant`	Atualize as propriedades de autoatendimento permitidas.
Excluir	`DELETE /!mytenant`	Exclua permanentemente os dados tenant e todos os tenant do chamador.

O autoatendimento usa direitos de acesso tenant e não pode administrar outro tenant. Alterações de plano, configurações de pagamento e domínios personalizados também estão sujeitos às políticas configuradas da implantação.

Altere o host nestes exemplos para uma implantação auto-hospedada e envie o token de acesso no cabeçalho Authorization: Bearer {access_token}.

Liste e identifique tenants

GET /!tenants aceita filterName, filterCustomDomain e paginationToken. Quando ambos os filtros são fornecidos, um tenant é retornado quando seu nome ou domínio personalizado corresponde. Os registros master tenant e tenant somente para uso interno não estão incluídos.

Repita uma solicitação paginada com os mesmos filtros e o token opaco retornado até que nenhum token seja retornado. Não interprete ou modifique o token.

O tenant name minúsculo é o identificador estável usado em URLs FoxIDs e Control API. Trate-o como uma chave de automação imutável. Um domínio personalizado é uma propriedade separada de roteamento e marca e não deve ser usado como o nome da Control API rota tenant.

Provisionar um tenant

A criação de Tenant é uma operação de provisionamento composta. Uma solicitação bem-sucedida cria:

o registro tenant;
o ambiente master do tenant e seu método de autenticação de login padrão;
o usuário administrador inicial;
o recurso Control API e o aplicativo Control Client;
os ambientes padrão configurados da implantação.

O administrador inicial pode receber uma senha fornecida ou estabelecer uma senha por meio do fluxo de email configurado. Proteja qualquer senha fornecida e não registre o corpo da solicitação.

A solicitação também pode selecionar um plano e inicializar configurações de cliente, declarações e domínio personalizado onde a implantação permitir. A exclusividade do nome Tenant, as regras do plano, o suporte ao domínio personalizado e os dados necessários do administrador são validados antes da conclusão do provisionamento. Se um erro de conta ou de dados interromper o provisionamento, FoxIDs tentará limpar os recursos criados por essa solicitação; no entanto, os clientes devem tratar qualquer falha como malsucedida e verificar o estado antes de tentar novamente com o mesmo nome tenant.

Atualizar tenant configurações

As operações Tenant PUT são atualizações completas, não patches. Obtenha o recurso atual, preserve todas as propriedades editáveis que devem permanecer inalteradas, aplique a alteração pretendida e envie o modelo de solicitação completo para o operador ou terminal de autoatendimento selecionado.

O recurso do operador inclui propriedades gerenciadas pela implantação, como atribuição de plano, verificação de domínio personalizado, configuração de uso e pagamento, moeda, IVA, preço por hora e dados do cliente. O recurso de autoatendimento expõe apenas as configurações que tenant tem permissão para gerenciar.

A alteração de um domínio personalizado por meio do autoatendimento marca o domínio como não verificado até que a verificação necessária seja concluída. O plano selecionado deve suportar um domínio personalizado. Use o operador API para gerenciar o estado de verificação; não permita que um cliente tenant não confiável afirme que seu próprio domínio foi verificado.

Excluir um tenant

A exclusão de Tenant é irreversível e em cascata. Ele exclui todos os ambientes no tenant e todos os aplicativos com escopo definido, métodos de autenticação, usuários, sessões, concessões, chaves e outros dados do FoxIDs. Ele também remove a configuração de nível tenant e o roteamento de domínio personalizado. O master tenant não pode ser excluído. Os logs já enviados para um repositório externo permanecem sujeitos à política de retenção e exclusão desse repositório.

Antes da exclusão, interrompa o tráfego, exporte configurações ou dados que devem ser retidos, cancele ou reconcilie o faturamento externo quando aplicável e verifique o nome técnico do tenant. Exigir confirmação explícita nas ferramentas do operador. Não use a exclusão tenant para desabilitar o acesso temporariamente; em vez disso, desabilite ou atualize os usuários, aplicativos ou métodos de autenticação relevantes.

Orientação sobre automação e segurança

Prefira terminais de autoatendimento quando um cliente precisar gerenciar apenas seu próprio tenant.
Restrinja as credenciais do operador a um serviço de provisionamento pequeno e confiável.
Mantenha o nome técnico tenant estável e armazene-o independentemente dos dados de exibição, do cliente e do domínio personalizado.
Use get-modify-put para que novas propriedades não sejam redefinidas por uma integração mais antiga.
Use paginação para tenant inventários e reconcilie por nome técnico.
Trate a criação e exclusão de tenant como ações de administração composta de longa duração; use tempos limite de cliente apropriados e verifique o estado final após uma resposta interrompida.
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 Request quando os dados de tenant, administrador, plano, pagamento, cliente ou domínio personalizado são inválidos.
401 Unauthorized quando o token de acesso está ausente ou é inválido.
403 Forbidden quando o chamador não possui o direito de acesso master ou tenant necessário.
404 Not Found quando o tenant selecionado não existe.
409 Conflict quando já existe um nome tenant ou outro valor exclusivo.

Use o corpo da resposta para detalhes de validação e Swagger UI para as respostas declaradas por cada operação.