Fundamentos

Tudo no nulvless parte de um conjunto pequeno de objetos. Com eles claros, o resto da documentação é mais detalhe do que conceito.

Organização, projeto, ambiente

Uma organização é dona da cobrança e dos membros. Um projeto é um produto, e vive dentro de uma organização. Um ambiente é uma cópia completa desse projeto — com usuários, sessões, provedores, templates e chaves próprios.

Ambientes não são uma flag numa linha. develop e main são bancos separados que nunca compartilham dados, e cada um responde na sua própria URL de issuer — main fica com o slug puro do projeto, e todo outro ambiente recebe o slug dele como sufixo. Mover configuração entre eles é uma promoção deliberada e registrada.

organização
└── projeto
    ├── ambiente · main         → acme.nulvless.co
    ├── ambiente · staging      → acme-staging.nulvless.co
    └── ambiente · develop      → acme-develop.nulvless.co

É por isso que um usuário de teste nunca aparece em produção: ele nunca esteve naquele banco. Como a configuração anda para frente está em Ambientes.

Usuários e identidades

Um usuário é uma pessoa dentro de um ambiente. Uma identidade é uma forma dessa pessoa provar quem é — uma senha, uma conta Google, uma conta GitHub.

Um usuário pode ter várias identidades. Quem se cadastrou com senha e depois continuou com o Google segue sendo um usuário só, com um id só e um histórico só.

Sessões

Uma sessão é um período autenticado de um usuário em um dispositivo. Ela registra o dispositivo, a localização e os métodos usados para chegar até ela.

Sessões são revogáveis uma a uma, e carregam se o modo sudo está ativo.

Papéis, escopos, grants e contextos

A autorização é baseada em papéis, com duas peças que a fazem funcionar em produtos multi-tenant.

• Um escopo é a menor unidade — uma coisa que pode ser feita, como projects:write.
• Um papel é um conjunto nomeado de escopos, como admin.
• Um contexto é onde o papel se aplica: uma organização, um projeto, ou qualquer recurso seu.
• Um grant é um usuário com um papel dentro de um contexto.

Como o grant carrega o contexto, a mesma pessoa pode ser owner numa organização e viewer em outra, sem o seu código tratar caso especial.

const { data } = await nulvless.auth.verify({
  resource: 'proj_16tbwq34',
  roles: ['owner', 'admin'],
});

Chaves

Cada ambiente tem as suas chaves.

• Uma chave publicável (pk-…) é segura no navegador. Ela só faz o que o usuário autenticado já poderia fazer.
• Uma chave secreta (sk-…) é só de servidor. Ela alcança as partes administrativas da API e nunca deve aparecer em código de cliente.

Qual chave você tem decide qual client você cria — veja Clients.

Tokens

O login devolve um access token e um refresh token. O access token é um JWT que seus serviços leem direto: ele carrega o usuário, os papéis e escopos dele, e as claims customizadas que você configurou.

É esse o ponto de colocar claims no token — um serviço que já lê o token não precisa de uma segunda chamada para saber o que quem chamou pode fazer.

Resultados, não exceções

Todo método do SDK devolve um objeto de resultado em vez de lançar exceção:

const { data, error } = await nulvless.auth.signIn({ email, password });

if (error) {
  // trate aqui — error.code, error.message, error.status_code
  return;
}

O caminho de erro é algo que você trata, não algo que você captura. Veja Error handling.