Skip to content

Perfis de Acesso

Visão Geral

Os escopos de permissão funcionam como o mecanismo central de controle de acesso da API.

Cada escopo representa uma permissão específica e é validado por meio de Middlewares, que recebem os códigos de escopo associados ao perfil do usuário.

Ao tentar acessar um módulo ou rota, o Middleware verifica se o usuário possui o escopo necessário; caso contrário, a ação é bloqueada.

Notas e Considerações

Um novo escopo só pode ser cadastrado a partir de inserções diretas no banco e não pode ser manipulado por um usuário admin.

Cada escopo é definido diretamente nos endpoints da API, ação que depende de um desenvolvedor.

Se deseja que um usuário tenha acesso liberado a algum módulo, certifique-se de vincular o escopo de permissão ao perfil de acesso do indivíduo. Sem isso, a validação do Middleware sempre vai barrar o usuário.

Listar Escopos do Usuário

GET /auth/scopes

Obtém lista de escopos/permissões disponíveis na loja

Descrição

Retorna uma lista de todos os escopos de permissões presentes na loja.

Parâmetros de Query

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/auth/scopes \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": [
4    {
5			"id": 1,
6			"code": "SCOPE_1_READ",
7			"description": "Escopo de permissão de leitura de x"
8		},
9		{
10			"id": 2,
11			"code": "SCOPE_2_WRITE",
12			"description": "Escopo de permissão para escrita de y"
13		}
14  ]
15}

Listar Escopos do Usuário Autenticado

GET /auth/users/scopes

Obtém lista de escopos/permissões do usuário autenticado

Descrição

Endpoint responsável por retornar todos os escopos (permissões) disponíveis para o usuário atualmente autenticado.

Os escopos são determinados pelo perfil de acesso do usuário e controlam quais funcionalidades e recursos ele pode acessar no sistema.

Parâmetros de Query

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/auth/users/scopes \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": [
4    "USER_READ",
5    "USER_WRITE",
6    "PRODUCT_READ",
7    "PRODUCT_WRITE",
8    "ORDER_READ",
9    "ORDER_WRITE",
10    "DASHBOARD_ACCESS",
11    "CUSTOMER_READ",
12    "CUSTOMER_WRITE",
13    "REPORT_READ",
14    "SETTING_READ",
15    "SETTING_WRITE",
16    "PROFILE_READ",
17    "PROFILE_WRITE",
18    "INTEGRATION_READ",
19    "INTEGRATION_WRITE"
20  ]
21}

Listagem de permissões do usuário por id

GET /auth/profile/{profileId}/scopes

Listar todas as permissões de um perfil.

Descrição

Endpoint responsável por listar todos os escopos de permissão associados a um perfil de usuário da loja.

Parâmetros de Query

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
profileIdintegerSimID único do perfil de usuário

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/auth/profile/{profileId}/scopes \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": [
4    "APP_VIEW",
5    "APP_CONFIGURE",
6    "USER_VIEW",
7    "USER_MODIFY",
8    "PROFILE_MANAGEMENT"
9  ]
10}

Verificação de permissão para usuário atual

GET /auth/users/check-scope/{scope}

Endpoint responsável por verificar se o usuário atual possui a permissão especificada

Descrição

Permite verificar se o usuário atualmente autenticado possui um determinado escopo de permissão.

Parâmetros de Query

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
scopestringSimCódigo do escopo

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/auth/users/check-scope/{scope} \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2	"status": true,
3	"data": true
4}

Observação: O campo "data" com o valor "false" indica que o usuário não tem o scopo solicitado.

Atualização de escopos de permissão

PUT /auth/profile/{profileId}/scopes

Esta rota possibilita definir e alterar as permissões de um determinado perfil

Descrição

Endpoint responsável por vincular escopos de permissão a um perfil de acesso, de modo que qualquer usuário utilizando esse perfil receba ou perca permissões, sejam elas de visualização ou alteração.

Parâmetros de query

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {token}Token de autenticação do usuário

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
profileIdintegerSimID do perfil de usuário

Parâmetros do Corpo

Esta rota segue um formato chave-valor, no qual é necessário informar um array com o código do escopo como chave e um valor booleano para determinar o vínculo.

ParâmetroTipoObrigatórioDescrição
{scope}string✅Código do escopo de permissão
1{
2	"DASHBOARD_READ": true,
3  "ORDER_READ": true,
4  "CART_READ": true,
5  "CART_WRITE": false,
6  "BUDGET_READ": false,
7  "BUDGET_WRITE": false,
8  "PRODUCT_READ": true,
9  "PRODUCT_WRITE": true,
10  "PRODUCT_PRICE_WRITE": true,
11  "PRODUCT_STOCK_WRITE": false,
12  "ATTRIBUTE_READ": true
13}

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/auth/profile/{profileId}/scopes \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "DASHBOARD_READ": true,
6    "ORDER_READ": true,
7    "CART_READ": true,
8    "CART_WRITE": false,
9    "BUDGET_READ": false,
10    "BUDGET_WRITE": false,
11    "PRODUCT_READ": true,
12    "PRODUCT_WRITE": true,
13    "PRODUCT_PRICE_WRITE": true,
14    "PRODUCT_STOCK_WRITE": false,
15    "ATTRIBUTE_READ": true
16  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": true
4}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código InternoCódigo HttpDescrição
UAPPI_AUTH_PROFILE_NOT_FOUND404O perfil solicitado não existe

Uappi é a melhor opção para o crescimento da sua loja!

Institucional

;