> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Usando o Access Manager

> Use as APIs do Access Manager para configurar acesso humano, acesso machine-to-machine, MFA e autenticação baseada em token.

O Access Manager é como você decide quem alcança seus produtos Lerian e como os sistemas provam quem são antes de chamar uma API protegida. Este guia percorre essa configuração com as APIs.

Se você prefere trabalhar de forma visual para as tarefas comuns de usuários e aplicações, use o [Access Manager via Lerian Console](/pt/platform/access-manager/using-access-manager-with-midaz-console).

## Antes de começar

***

Primeiro, confirme que o Access Manager está habilitado para os produtos que você quer proteger. A partir daí, toda API protegida espera um header `Authorization` carregando um bearer token válido.

```text theme={null}
Authorization: Bearer <access_token>
```

<Warning>
  Requisições sem um bearer token válido são rejeitadas após o Access Manager ser habilitado, mesmo que o endpoint fosse acessível antes sem autenticação.
</Warning>

Em deployments SaaS e BYOC multi-tenant, esse token também carrega o contexto do seu tenant em claims confiáveis, como `tenantId`, então você nunca passa identificadores de tenant em payloads ou headers por conta própria. Saiba mais sobre [multi-tenancy](/pt/multi-tenancy).

Com as APIs do Identity, o token também é seu limite de tenant: endpoints de listagem retornam apenas os usuários, grupos e aplicações do seu tenant, e as operações de criação, atualização e exclusão permanecem dentro dele.

## Acesso humano

***

Siga este fluxo quando uma pessoa precisar acessar produtos Lerian.

<Steps>
  <Step title="Inspecione os grupos disponíveis">
    Use [Listar Grupos](/pt/reference/access-manager/list-groups) para ver os grupos disponíveis no seu ambiente.

    Use [Recuperar detalhes do Grupo](/pt/reference/access-manager/retrieve-group-details) quando precisar inspecionar as permissões de um grupo específico antes de atribuí-lo.

    Em deployments multi-tenant, a lista é escopada ao tenant carregado pelo bearer token. Use os IDs de grupo retornados como estão ao criar ou atualizar usuários.
  </Step>

  <Step title="Revise a superfície de permissões">
    Verifique os resources e actions de cada grupo antes de atribuí-lo. As permissões do Access Manager são avaliadas como pares resource-action exatos, como `reports:get`, `users:patch` ou `transfers:read`.

    Alguns produtos usam actions no estilo de métodos HTTP, enquanto outros usam actions semânticas como `read`, `write`, `create` ou `process`. Use as permissões retornadas pela API em vez de derivar nomes de permissão a partir de paths de endpoint.
  </Step>

  <Step title="Crie o usuário">
    Use [Criar um Usuário](/pt/reference/access-manager/create-user) e atribua os grupos corretos durante a criação.

    A atribuição de grupos define o que o usuário pode acessar. Por exemplo, atribuir um grupo Midaz somente leitura permite que o usuário inspecione resources do Midaz sem alterá-los.
  </Step>

  <Step title="Solicite um token de usuário">
    Use [Solicitar um Access Token](/pt/reference/access-manager/request-access-token) com o grant type `password`.

    O access token retornado é usado como bearer token quando o usuário chama APIs protegidas.
  </Step>

  <Step title="Renove o token quando necessário">
    Use [Atualizar o Access Token](/pt/reference/access-manager/refresh-token) para trocar um refresh token válido por um novo access token.
  </Step>
</Steps>

### Endpoints de gerenciamento de usuários

Use estes endpoints para manter o acesso humano ao longo do tempo:

* [Listar Usuários](/pt/reference/access-manager/list-users) — lista os usuários.
* [Recuperar detalhes do Usuário](/pt/reference/access-manager/retrieve-user-details) — inspeciona um usuário.
* [Atualizar um Usuário](/pt/reference/access-manager/update-user) — atualiza as informações e atribuições de grupo do usuário.
* [Excluir um Usuário](/pt/reference/access-manager/delete-user) — remove o acesso de um usuário.
* [Redefinir Senha do Usuário](/pt/reference/access-manager/reset-user-password) — redefine a senha de um usuário por um fluxo administrativo.
* [Atualizar Senha do Usuário](/pt/reference/access-manager/update-user-password) — atualiza a senha de um usuário com a senha atual e a nova.

## Acesso machine-to-machine

***

Quando um serviço, job ou integração precisa chamar APIs Lerian sem um humano no fluxo, dê a ele sua própria aplicação.

<Steps>
  <Step title="Crie uma aplicação">
    Use [Criar uma Aplicação](/pt/reference/access-manager/create-an-application) para criar credenciais para a integração.

    Cada integração deve ter sua própria aplicação. Isso facilita a rotação de credenciais e a revisão de acesso. A resposta inclui o `clientId` e o `clientSecret` usados pelo Auth no fluxo `client_credentials`.
  </Step>

  <Step title="Revise ou gerencie a aplicação">
    Use [Listar Aplicações](/pt/reference/access-manager/list-applications), [Recuperar detalhes da Aplicação](/pt/reference/access-manager/retrieve-application-details) ou [Excluir Aplicação](/pt/reference/access-manager/delete-application) quando precisar revisar ou remover acesso machine-to-machine.

    O Identity esconde aplicações internas da lista. Em deployments multi-tenant, ele retorna apenas as aplicações vinculadas à organização de tenant do solicitante.
  </Step>

  <Step title="Solicite um token de aplicação">
    Use [Solicitar um Access Token](/pt/reference/access-manager/request-access-token) com o grant type `client_credentials`.

    O access token retornado é usado como bearer token para as chamadas de API da integração.
  </Step>
</Steps>

### Catálogo atual de aplicações M2M

O seed e as migrations atuais do Access Manager definem permissões M2M para estes nomes de aplicação:

| Nome da aplicação            | Produto          |
| ---------------------------- | ---------------- |
| `midaz`                      | Midaz Ledger     |
| `plugin-fees`                | Fees Engine      |
| `plugin-crm`                 | CRM              |
| `reporter`                   | Reporter         |
| `plugin-br-pix-direct-jd`    | Pix Direct JD    |
| `plugin-br-pix-indirect-btg` | Pix Indirect BTG |
| `plugin-br-bank-transfer`    | Bank Transfer    |

Outros produtos listados na matriz de habilitação, como Tracer, Flowker e Fetcher, atualmente não definem nomes padrão de aplicações M2M no seed do Access Manager.

Não crie aplicações com nomes fora deste catálogo, a menos que seu ambiente tenha um permission set customizado para aquela aplicação.

## Configuração de providers

***

Use providers quando uma aplicação precisar de um provedor de comunicação configurado para entrega de MFA, como email ou SMS.

1. Crie ou revise um provider com a [API de Providers](/pt/reference/access-manager/list-providers).
2. Vincule o provider à aplicação com [Vincular Provider à Aplicação](/pt/reference/access-manager/link-provider-to-application).
3. Se a aplicação tiver múltiplos providers vinculados, use [Definir Provider Padrão da Aplicação](/pt/reference/access-manager/set-default-application-provider) para selecionar o provider padrão.

Use os endpoints de application-provider quando precisar listar, atualizar, desvincular ou reordenar os vínculos de provider de uma aplicação.

## Configuração de MFA

***

Use MFA para usuários que precisam de uma etapa adicional de verificação no login.

<Steps>
  <Step title="Inicie a configuração">
    Use [Iniciar Configuração de MFA](/pt/reference/access-manager/initiate-mfa-setup) para o usuário e o método de MFA.
  </Step>

  <Step title="Verifique a configuração">
    Use [Verificar Passcode de MFA](/pt/reference/access-manager/verify-mfa-passcode) para confirmar o método.
  </Step>

  <Step title="Habilite o MFA">
    Use [Habilitar MFA](/pt/reference/access-manager/enable-mfa) após a verificação da configuração.
  </Step>

  <Step title="Gerencie o MFA ao longo do tempo">
    Use [Obter Status do MFA](/pt/reference/access-manager/get-mfa-status), [Definir Método de MFA Preferido](/pt/reference/access-manager/set-preferred-mfa-method) ou [Desabilitar MFA](/pt/reference/access-manager/disable-mfa) conforme os requisitos de acesso do usuário mudam.
  </Step>
</Steps>

Durante o login, usuários com MFA habilitado podem precisar concluir [Iniciar Desafio de MFA](/pt/reference/access-manager/initiate-mfa-challenge) e [Verificar Login com MFA](/pt/reference/access-manager/verify-mfa-login) antes de receber access tokens utilizáveis.

## Informações do usuário e controle de sessão

***

Quando um usuário está ativo, alguns endpoints ajudam a inspecionar e controlar a sessão. [Recuperar Informações do Usuário](/pt/reference/access-manager/retrieve-user-information) retorna o perfil compatível com OIDC dele, e [Recuperar Permissões do Usuário](/pt/reference/access-manager/retrieve-user-permissions) mostra os resources e actions que ele pode alcançar. Quando você precisa encerrar uma sessão antes da hora e revogar seus tokens ativos, chame [Encerrar Sessão do Usuário](/pt/reference/access-manager/end-user-session).

## Verificações de permissão

***

Produtos protegidos chamam o Auth com o resource e a action que precisam aplicar. Use [Validar Permissão do Usuário](/pt/reference/access-manager/validate-user-permission) quando uma integração precisar verificar explicitamente uma decisão de acesso.

```json theme={null}
{
  "resource": "reports",
  "action": "get"
}
```

A resposta informa se o subject autenticado está autorizado para aquele par resource-action.

## Regras de acesso multi-tenant

***

O fluxo de trabalho da API é idêntico em deployments single-tenant e multi-tenant. A única coisa que muda é de onde o Access Manager obtém o escopo do tenant:

* Em deployments multi-tenant, Auth e Identity resolvem o tenant a partir do token confiável ou do contexto da aplicação.
* Em deployments single-tenant, o Access Manager usa a organização padrão configurada.

Por isso, não adicione tenant IDs aos payloads de Identity ou Auth, a menos que um endpoint documente explicitamente esse campo. Para os fluxos normais de usuário, grupo, aplicação, token e permissão, o bearer token é sua única fonte de escopo de tenant.