Skip to main content
Uma organização é a fronteira de tenancy. Toda linha que pertence a um cliente pende de organization_id, e toda consulta filtra por ele. Um usuário chega a uma organização por um vínculo (membership), que carrega exatamente um papel. Um usuário pode ter vínculos em várias organizações; o seletor do painel é essa lista.

​
O código público

Toda organização tem um public_code no formato org_<32 hex>. É ele que aparece na URL do painel e viaja no header X-Organization-Id.
É opaco e imutável de propósito: renomear uma organização nunca pode quebrar um link. E ele identifica sem autorizar — colar o código de outra pessoa na URL não resolve sessão nenhuma, porque o JOIN do vínculo não casa com nada.
O UUID interno nunca sai da API nas superfícies que o painel usa. Use public_code em URLs e headers.

​
Criando uma

O cadastro cria a primeira organização. Um usuário autenticado pode abrir outras, tornando-se owner de cada uma:
A sessão troca para a nova organização na hora — ninguém cria um workspace para depois sair procurando por ele. Três invariantes são estabelecidas nessa mesma transação, e valem por toda a vida da organização:
  • ela sempre tem os três papéis de sistema (owner, admin, member);
  • ela sempre tem um owner;
  • ela sempre tem um ambiente live e um test, cada um com sua chave publicável.

​
Trocando

Trocar é navegação, não um estado que você precise gerenciar. O vínculo é verificado toda vez, e trocar para uma organização da qual você não faz parte responde 404 — nunca um vazamento de que ela existe.

​
Convidando pessoas

Um convite é criado contra um papel e enviado por e-mail como link de uso único, válido por 7 dias. Um convite pendente por endereço, garantido por um índice único parcial — então um duplo clique não produz dois.
Ler o convite informa à tela de aceite se o endereço já tem conta (existing_account), para ela saber se pede nome e senha. Uma conta existente entra direto — o convite foi para aquele endereço, e possuir o link já prova o suficiente. O convite existe mesmo quando o e-mail se perde. Revogue e convide de novo.

​
Sair e remover

Duas ações diferentes, deliberadamente: Sair é um usuário administrando o próprio acesso, então não passa por members:write. Remover a si mesmo pelo primeiro endpoint responde 403 com uma mensagem apontando para o segundo. A remoção vale já na próxima requisição da pessoa: o JOIN do vínculo da sessão deixa de casar.

​
A guarda do último owner

Uma organização precisa manter pelo menos um owner. Rebaixar, remover ou sair como último owner responde:
409
A guarda trava as linhas de owner antes de contar, então dois rebaixamentos concorrentes de owners diferentes serializam em vez de ambos lerem “2 owners” e deixarem a organização sem dono.

​
Deletando

Só owner (organization:delete), e o nome exato precisa ser digitado de volta:
Tudo cai em cascata: vínculos, papéis, chaves, convites, ambientes, contatos e as sessões presas a ela. Um nome que não bate responde 400 confirmation_mismatch.