auth.admin

A linha a ter em mente: o auth.grants é um usuário fazendo algo, o auth.admin.grants é o seu back office fazendo algo. Recorrer ao admin porque é mais fácil remove justamente a verificação que você queria.

Quatro namespaces ficam sob auth.admin:

admin.users

create · list · get · update · delete · ban · unban

await nulvless.auth.admin.users.create(params);
await nulvless.auth.admin.users.list({ page, page_size });
await nulvless.auth.admin.users.get(userId);
await nulvless.auth.admin.users.update(userId, params);
await nulvless.auth.admin.users.delete(userId);

create

Diferente do auth.signUp, nada é estritamente obrigatório aqui, porque um admin pode estar semeando um registro antes da pessoa. Um usuário sem identidade não consegue entrar, então passe pelo menos um entre email, phone ou username, a menos que esse seja o objetivo.

Quando todas as credenciais enviadas estão marcadas como verificadas (email com email_verified, phone com phone_verified), o usuário é criado confirmado: nenhuma confirmação é enviada, nenhuma sessão é criada e ele já pode entrar. Caso contrário, o usuário passa pela confirmação definida nas configurações de cadastro da plataforma, como um link enviado para o e-mail.

list

Devolve Paginated<User>.

update

Recebe o userId, e então um conjunto mais estreito que o do create:

Identidades estão deliberadamente ausentes. Um e-mail ou telefone é trocado pelo fluxo confirmado próprio dele em auth.users, nunca editado no lugar por um admin — caso contrário um administrador poderia apontar uma conta para um endereço que ninguém provou ser seu.

Os mesmos campos são editáveis pela própria pessoa através do auth.users.update. Recorra ao caminho de admin só quando estiver agindo sobre outra pessoa.

Cortando acesso

await nulvless.auth.admin.users.ban(userId);
await nulvless.auth.admin.users.unban(userId);

Banir impede a entrada e deixa todo o resto intacto, então o histórico ligado à conta ainda resolve. Excluir é para quando o registro em si precisa sumir — lembre que os grants dela não desaparecem junto, então limpe também.

Sessões e fatores

await nulvless.auth.admin.users.getSessions(userId);
await nulvless.auth.admin.users.revokeSession(userId, sessionId);
await nulvless.auth.admin.users.signOutAll(userId);

await nulvless.auth.admin.users.getFactors(userId);
await nulvless.auth.admin.users.removeFactor(userId, factorId);

O signOutAll é o que você chama depois de um comprometimento — ele encerra todas as sessões da pessoa, em todo lugar.

admin.roles

list · create · update · delete

Um papel é um conjunto nomeado de escopos dentro de um contexto. Mudar os escopos de um papel muda o que todo mundo que o tem pode fazer, sem tocar em um único grant — que é por isso que é nele, e não no grant, que mudanças de permissão devem morar.

create

const { data: role } = await nulvless.auth.admin.roles.create({
  name: 'Administrator',
  key: 'admin',
  context: 'org',
  scopes: ['members:read', 'members:write', 'projects:read'],
});

list

list(context) → Role[]

const { data: roles } = await nulvless.auth.admin.roles.list('org');

Os papéis definidos para um contexto. É daqui que vêm os valores de role_id para o grants.invite — leia uma vez na inicialização e mapeie, em vez de consultar a cada convite.

update

Recebe o role_id, e então name, description ou scopes. key e context são fixos, porque mudar qualquer um reinterpretaria silenciosamente todo grant existente.

admin.grants

list · set · delete · deleteByResource

set

Atribui acesso diretamente — sem convite, sem passo de aceite. O grant existe imediatamente com status: 'granted'.

await nulvless.auth.admin.grants.set({
  resource: org.slug,
  granted_to_user_id: creatorId,
  role_id: ownerRoleId,
});

O uso canônico é semear o primeiro dono. Quem criou um recurso não deveria ter que aceitar um convite para ele, e fazer isso na mesma transação que cria o recurso significa que uma falha não deixa um órfão que ninguém consegue administrar.

list

Devolve Paginated<Grant>. Filtrar por granted_to_user_id responde "o que esta pessoa alcança?" — a pergunta de back office que o auth.grants.list responde apenas para quem chamou.

deleteByResource

await nulvless.auth.admin.grants.deleteByResource(org.slug);

Limpa todo grant de um recurso de uma vez. Chame quando um projeto ou organização for excluído.

admin.oauthClients

create · list · get · update · delete · regenerateSecret

await nulvless.auth.admin.oauthClients.create(params);
await nulvless.auth.admin.oauthClients.list();
await nulvless.auth.admin.oauthClients.get(id);
await nulvless.auth.admin.oauthClients.update(id, params);
await nulvless.auth.admin.oauthClients.delete(id);
await nulvless.auth.admin.oauthClients.regenerateSecret(id);

Estas são as aplicações autorizadas a pedir tokens ao seu issuer — o outro lado do auth.oauth.

O regenerateSecret rotaciona um client secret e o antigo para de funcionar imediatamente. Não há janela de sobreposição, então combine com quem opera aquela integração em vez de tratar como higiene de rotina.

Próximos