Convidando um colega e gerenciando sua role com RBAC

Toda Organização na rollfuse é um jardim fechado: ninguém entra sem convite, e ninguém age além do que sua role permite. Este tutorial cobre o ciclo completo: enviar o convite, aceitar, e conceder ou revogar uma role assim que a pessoa vira Membro.

Como funciona o RBAC aqui

Um Membro é a conta dentro da sua Organização; uma Role define o que esse Membro pode fazer. Por padrão, um Membro não tem nenhuma role até que uma seja concedida. Conceder a role member tem efeito imediato. Já conceder a role admin é mais sensível e não é aplicada na hora: ela abre uma aprovação pendente, que precisa ser confirmada por um segundo Membro, diferente do primeiro, que também tenha permissão para gerenciar roles. Essa regra de dois pares de olhos existe justamente para que ninguém consiga se autopromover de forma silenciosa.

Todas as chamadas abaixo exigem um token de sessão de um Membro com permissão para gerenciar membros e roles na sua Organização. Troque token, orgId e os ids dos exemplos pelos seus.

Passo 1: enviar o convite

const orgId = "018f2f3a-6000-7000-9c3a-1f2b3c4d5e6f";
const token = process.env.ROLLFUSE_SESSION_TOKEN;

const inviteRes = await fetch(
  `https://api.rollfuse.com/v1/organizations/${orgId}/invites`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email: "dev@example.com" }),
  }
);

const invite = await inviteRes.json();
console.log(invite.status); // "pending"

O corpo carrega só o e-mail: o convite sempre é emitido dentro da sua própria Organização, então não existe campo para direcioná-lo a outra. A resposta é um MemberInviteResponse com o id do convite, seu status (pending), um expires_at de sete dias e nenhum token: o link de aceite com o token real só é enviado por e-mail ao endereço convidado.

Se precisar cancelar o convite antes de ele ser usado, revogue assim:

await fetch(
  `https://api.rollfuse.com/v1/organizations/${orgId}/invites/${invite.id}`,
  { method: "DELETE", headers: { Authorization: `Bearer ${token}` } }
);

Passo 2: aceitar o convite

Aceitar é a única chamada desse fluxo que não exige autenticação: o token embutido no link enviado por e-mail é a própria credencial. Ele viaja como parâmetro de query, não no corpo da requisição.

const acceptRes = await fetch(
  `https://api.rollfuse.com/v1/invites/accept?token=${encodeURIComponent(inviteToken)}`,
  { method: "POST" }
);

const accepted = await acceptRes.json();
console.log(accepted.member_id, accepted.organization_id);

Isso cria o registro de Membro, mas sem nenhuma role atribuída e sem sessão: o novo colega faz login depois pelo fluxo normal da sua Organização. Qualquer problema com o token (desconhecido, expirado, revogado, já usado) volta com o mesmo erro genérico, de propósito, para que ninguém tentando adivinhar links de convite descubra qual desses casos realmente aconteceu.

Passo 3: conceder uma role

Com o Membro já existindo, conceda a role adequada para a função dele. Aqui concedemos member, que é imediata:

const grantRes = await fetch(
  `https://api.rollfuse.com/v1/members/${accepted.member_id}/roles`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ role: "member" }),
  }
);

const grant = await grantRes.json();
console.log(grant.status); // "granted"

Conceder admin, por outro lado, retorna status: "pending_approval": a atribuição só é criada depois que um admin diferente aprova a solicitação (veja o passo de aprovação no tutorial de auditoria e aprovações). Conceder uma role que o Membro já possui é rejeitado como conflito, então vale sempre checar o status da resposta em vez de assumir sucesso.

Passo 4: revogar uma role

Se alguém muda de time ou sai da empresa, remova a role que ela não precisa mais:

await fetch(
  `https://api.rollfuse.com/v1/members/${accepted.member_id}/roles/member`,
  { method: "DELETE", headers: { Authorization: `Bearer ${token}` } }
);

Revogar uma role que o Membro não possui é rejeitado; revogar uma entre várias roles que o Membro detém deixa as outras intactas, então dá para remover exatamente o acesso que você quer, sem afetar o resto.