Funções e Permissões

Hierarquia de funções, permissões e como elas restringem os endpoints da API.

A Reten implementa Controle de Acesso Baseado em Funções (RBAC) hierárquico, com permissões granulares agrupadas por domínio. As tabelas abaixo listam todas as permissões, agrupadas pelos mesmos domínios que a API usa; um usuário com várias funções tem as permissões de todas elas.

As permissões e as funções são escritas como o valor que a API envia e recebe: activity:view, admin. Esse é o valor que você envia em permissions de POST /api/api-keys e em roles de POST /api/auth/register, e o que a API retorna em um 403 — Required permissions: activity:view.

Hierarquia de Funções

super_admin (máximo)
    │
    ▼
  admin
    │
    ▼
   fde
    │
    ▼
supervisor
    │
    ▼
 operator
    │
    ▼
  viewer (mínimo)

Cada função tem sua própria lista explícita de permissões: uma função superior não tem automaticamente todas as permissões das funções inferiores (por exemplo, supervisor tem activity:force-retry-dispatch e fde não). A hierarquia rege o gerenciamento de usuários: um usuário só pode gerenciar usuários cuja função seja estritamente inferior à sua.

Funções

Função	Nível	Descrição
`super_admin`	6 (máximo)	Acesso total ao sistema; pode gerenciar todos os usuários e tenants
`admin`	5	Administração do tenant; pode gerenciar a maioria dos recursos
`fde`	4	Field Development Engineer com acesso padrão: gerencia projetos, comércios, operadores, rotas, audiências e atividades
`supervisor`	3	Supervisiona os operadores de campo: visualiza atividades, registra e edita resultados, e pode forçar um novo despacho de atividades que falharam
`operator`	2	Operador de campo com acesso restrito às atividades atribuídas a ele: visualiza-as e registra seus resultados; também pode gerenciar comércios
`viewer`	1 (mínimo)	Acesso somente leitura aos dados do tenant

Permissões por Domínio

Domínio de Usuários

Permissão	Descrição	Funções
`user:create`	Criar novos usuários	`super_admin`, `admin`
`user:view`	Listar usuários do tenant	`super_admin`, `admin`, `fde`, `supervisor`, `viewer`
`user:update`	Substituir as funções de um usuário (`PUT /api/user/:id/roles`)	`super_admin`, `admin`
`user:delete`	Hoje nenhum endpoint a exige	`super_admin`, `admin`
`user:reset-password`	Redefinir a senha de outro usuário	`super_admin`, `admin`

Domínio de Tenants

Permissão	Descrição	Funções
`tenant:create`	Criar novos tenants	`super_admin`
`tenant:view`	Listar todos os tenants	`super_admin`, `admin`
`tenant:update`	Atualizar dados do tenant	`super_admin`
`tenant:delete`	Hoje nenhum endpoint a exige	`super_admin`

Domínio de Projetos

Permissão	Descrição	Funções
`project:create`	Criar projetos junto com sua audiência raiz (`POST /api/projects`)	`super_admin`, `admin`, `fde`
`project:view`	Listar os projetos do tenant (`GET /api/projects`)	`super_admin`, `admin`, `fde`, `supervisor`, `operator`, `viewer`
`project:update`	Renomear projetos (`PATCH /api/projects/:id`) e editar sua audiência raiz	`super_admin`, `admin`, `fde`

Domínio de Comércios

Permissão	Descrição	Funções
`commerce:manage`	CRUD completo em comércios, endereços, usuários e contatos (excluir um comércio exige `commerce:delete`)	`super_admin`, `admin`, `fde`, `operator`
`commerce:batch-upsert`	Upsert em lote de comércios a partir de sistemas externos (`POST /api/integration/commerces/batch-upsert`)	`super_admin`, `admin`

Domínio de Estados de Ciclo de Vida de Comércios

Permissão	Descrição	Funções
`commerce-lifecycle-snapshot:view`	Listar e consultar os estados de ciclo de vida de comércios, incluindo o lookup por lote	`super_admin`, `admin`, `fde`, `supervisor`, `operator`, `viewer`
`commerce-lifecycle-snapshot:create`	Gravar estados de ciclo de vida de comércios: upsert individual e upsert por lote	`super_admin`, `admin`, `fde`, `supervisor`
`commerce-lifecycle-snapshot:sync`	Hoje nenhum endpoint a exige (o upsert por lote exige `commerce-lifecycle-snapshot:create`)	`super_admin`, `admin`, `fde`

Domínio de Operadores

Permissão	Descrição	Funções
`operator:manage`	CRUD completo em operadores (excluir um operador exige `operator:delete`)	`super_admin`, `admin`, `fde`
`operator:batch-upsert`	Upsert em lote de operadores a partir de sistemas externos (`POST /api/integration/operators/batch-upsert`)	`super_admin`, `admin`

Domínio de Rotas

Permissão	Descrição	Funções
`route:manage`	CRUD completo em rotas e atribuições de operadores (excluir uma rota exige `route:delete`)	`super_admin`, `admin`, `fde`
`route:batch-upsert`	Upsert em lote de rotas a partir de sistemas externos (`POST /api/integration/routes/batch-upsert`)	`super_admin`, `admin`

Domínio de Atividades

Permissão	Descrição	Funções
`activity:view`	Listar e visualizar atividades, resultados e configurações	`super_admin`, `admin`, `fde`, `supervisor`, `operator`, `viewer`
`activity:create`	Criar atividades (`POST /api/activities` e `POST /api/activities/bulk`)	`super_admin`, `admin`, `fde`
`activity:cancel`	Cancelar atividades	`super_admin`, `admin`, `fde`
`activity:dispatch`	Despachar manualmente atividades de tarefa	`super_admin`, `admin`
`activity:force-retry-dispatch`	Forçar um novo despacho de uma atividade `FAILED` (`PATCH /api/activities/:id/force-retry-dispatch`)	`super_admin`, `admin`, `supervisor`
`activity-config:manage`	Gerenciar configuração de atividades (activity setup) e configurações de despacho	`super_admin`, `admin`

Domínio de Audiências

Permissão	Descrição	Funções
`audience-criteria:create`	Criar audiências (`POST /api/audience-criterias`)	`super_admin`, `admin`, `fde`
`audience-criteria:view`	Listar e visualizar audiências, e explorar seu catálogo (`tables`, `tables/:tableName/columns`)	`super_admin`, `admin`, `fde`
`audience-criteria:update`	Atualizar audiências (`PATCH /api/audience-criterias/:id`); editar a audiência raiz exige também `project:update`	`super_admin`, `admin`, `fde`
`audience-criteria:delete`	Excluir audiências (`DELETE /api/audience-criterias/:id`)	`super_admin`, `admin`, `fde`
`audience-criteria:view-sql`	Gerar, validar e pré-visualizar o SQL de uma audiência	`super_admin`, `admin`, `fde`

Domínio de Filtros de Eventos

Permissão	Descrição	Funções
`event-criteria:create`	Criar filtros de eventos (`POST /api/event-criterias`)	`super_admin`, `admin`, `fde`
`event-criteria:view`	Listar e visualizar filtros de eventos, e explorar seu catálogo (`tables`, `tables/:tableName/columns`)	`super_admin`, `admin`, `fde`
`event-criteria:update`	Atualizar filtros de eventos (`PATCH /api/event-criterias/:id`)	`super_admin`, `admin`, `fde`
`event-criteria:delete`	Excluir filtros de eventos (`DELETE /api/event-criterias/:id`)	`super_admin`, `admin`, `fde`
`event-criteria:view-sql`	Gerar, validar e pré-visualizar o SQL de um filtro de eventos	`super_admin`, `admin`, `fde`

Domínio de Activity Generation e Ciclo de Vida

Permissão	Descrição	Funções
`activity-generation-config:view`	Ver AGCs e seus pilares de ciclo de vida (incl. os `configHashes` por pilar)	`super_admin`, `admin`
`activity-generation-config:create`	Criar uma AGC com seus 3 pilares de ciclo de vida	`super_admin`, `admin`
`activity-generation-config:update`	Atualizar metadados da AGC, substituir os pilares de ciclo de vida in-place, publicar e pausar	`super_admin`, `admin`
`activity-generation-config:delete`	Arquivar uma AGC (com efeito cascata sobre seus lifecycle configs)	`super_admin`, `admin`
`lifecycle-config:view`	Ver os lifecycle configs somente leitura (ativação / engagement / ressurreição)	`super_admin`, `admin`
`lifecycle-config:delete`	Interno — restringe o arquivamento/restauração de lifecycle na cascata da lixeira	`super_admin`, `admin`

Os lifecycle configs não têm permissões próprias de criação/edição/exclusão: um lifecycle config é criado e editado apenas por meio do fluxo da AGC, restringido por activity-generation-config:create / activity-generation-config:update.

Domínio de Provedores de Despacho

Permissão	Descrição	Funções
`dispatch-provider:manage`	Editar as definições de canal de um provedor de despacho: mapeamento de payload e configurações recomendados, e se o mapeamento é obrigatório (`PATCH /api/dispatch-providers/:providerId/channel-definitions/:definitionId`)	`super_admin`

Domínio de Consulta de Dados

Permissão	Descrição	Funções
`data-query:view`	Ler os metadados do catálogo de dados: tabelas e suas colunas (`GET /api/data-query/tables`, `GET /api/data-query/tables/:tableName/columns`)	`super_admin`, `admin`, `fde`

Domínio de API Keys

Permissão	Descrição	Funções
`api-key:manage`	Criar, listar, revogar e editar as permissões de API keys	`super_admin`, `admin`

Domínio de Resultados de Atividades

Permissão	Descrição	Funções
`activity-result:submit`	Registrar resultados de atividades (`POST /api/activity-results/tasks` e `POST /api/integration/activity-results/tasks`)	`super_admin`, `admin`, `fde`, `supervisor`, `operator`
`activity-result:edit`	Editar resultados de atividades (`PATCH /api/activity-results/tasks/:id`)	`super_admin`, `admin`, `fde`, `supervisor`, `operator`
`activity-result:sync-stream`	Ler o stream incremental de sincronização de resultados de tarefas (`GET /api/activity-results/tasks/sync`)	`super_admin`, `admin`

Domínio de Lixeira e Exclusão

Permissão	Descrição	Funções
`trash:view`	Ver os registros arquivados na lixeira e restaurá-los (`/api/trash`). Ver o detalhe ou a prévia da cascata de um registro e restaurá-lo também exigem a permissão que exclui esse tipo de registro (por exemplo, `commerce:delete`). Excluir um registro da lixeira definitivamente é restrito a `super_admin`	`super_admin`, `admin`, `fde`
`trash:manage-settings`	Ver e alterar as configurações de retenção da lixeira do tenant (`GET` e `PATCH /api/trash/settings`)	`super_admin`, `admin`
`commerce:delete`	Excluir comércios, que vão para a lixeira (`DELETE /api/commerces/:id`)	`super_admin`, `admin`, `fde`
`operator:delete`	Excluir operadores, que vão para a lixeira (`DELETE /api/operators/:id`)	`super_admin`, `admin`, `fde`
`route:delete`	Excluir rotas, que vão para a lixeira (`DELETE /api/routes/:id`)	`super_admin`, `admin`, `fde`
`supervisor:delete`	Excluir supervisores, que vão para a lixeira (`DELETE /api/supervisors/:id`)	`super_admin`, `admin`, `fde`

Acesso máquina a máquina (M2M) para computação

O motor de retenção que calcula os estados de ciclo de vida dos comércios lê as AGCs de forma programática. Ele usa uma API key (sem novo mecanismo de auth) que carrega activity-generation-config:view. Com essa permissão, ele chama GET /api/activity-generation-configs e GET /api/activity-generation-configs/:id para ler cada pilar e seu configHashes (para detectar de forma barata quando uma config mudou), e então grava os estados calculados de volta via commerce lifecycle snapshots. Os dois endpoints de AGC são project-scoped: com uma chave de tenant, cada chamada envia x-project-id (sem ele a API responde 400 — Falta el header obligatorio x-project-id.), e uma chave de projeto só lê as AGCs do seu próprio projeto — veja Escopo da chave.

Como as Permissões Restringem os Endpoints

Para rotas protegidas, a API verifica cada requisição nesta ordem:

Autenticação — O access token JWT ou a API key é válido (toda rota protegida)
Tenant — O usuário pertence ao tenant solicitado
Projeto — Nos endpoints project-scoped, o projeto ativo é válido (veja Autenticação → Contexto de Projeto)
Permissões — O usuário tem as permissões necessárias

Cada página de endpoint na referência da API lista a permissão necessária (ex.: Auth: Obrigatório — permissão activity:create).

Aplicação da Hierarquia de Funções

Usuários não podem modificar as funções de usuários no mesmo nível ou superior
Usuários não podem redefinir senhas de usuários no mesmo nível ou superior
Usuários não podem atribuir uma função igual ou superior à sua própria

Nos três casos a API responde 403.

Contexto de Tenant

A maioria dos endpoints exige um contexto de tenant:

Auth JWT: forneça o header x-tenant-id com o UUID do tenant
Auth API key: o tenant é resolvido automaticamente a partir da key

O sistema valida que o usuário autenticado pertence ao tenant solicitado antes de prosseguir.

Os endpoints project-scoped também precisam do projeto (veja Autenticação → Contexto de Projeto):

Auth JWT e chaves de tenant: forneça o header x-project-id com o UUID do projeto. Nos endpoints project-optional o header é opcional e restringe a requisição a esse projeto
Chaves de projeto: a chave sempre trabalha no seu próprio projeto, então o header não é necessário (veja Escopo da chave)