5 · A sua conta, as chaves e o console¶
Tudo o que você faz com a Stalwart é feito com uma chave de API, e toda chave depois da primeira é sua para criar no console web. Este capítulo trata de como uma conta é aberta, como se chega ao console, o que cada uma das suas páginas faz, quem pode fazer o quê, e como cuidar de uma chave: criá-la, guardá-la, trocá-la, revogá-la, e o que fazer quando uma vaza ou quando todas se perdem.
Abrindo uma conta¶
Cadastre-se na página de cadastro do site, com o Google ou com um link enviado por e-mail. Nenhuma pessoa da Stalwart participa.
- Com o Google, pede-se o seu endereço verificado e nada mais.
- Com um link por e-mail, você digita o seu endereço e um link é enviado a ele por
noreply@mail.stalwart.it. Um link de cadastro dura trinta minutos e só pode ser seguido uma vez. Nada é criado até que ele seja seguido.
Então a página de boas-vindas pede o nome da sua organização e que você aceite os termos e o adendo de tratamento de dados; as versões que você aceitou são registradas. Um único passo então abre uma conta gratuita, faz de você a sua proprietária e cria a sua primeira chave de produção, mostrada uma única vez, nessa página. Copie-a nesse momento: ninguém, nem nós, consegue mostrá-la de novo. O que o plano gratuito inclui, e o que pagar acrescenta, está no capítulo 40.
Uma conta enterprise é aberta sob contrato: escolha Plano enterprise na
página de contato do site, ou escreva para
newaccounts@stalwart.it.
O console¶
O console fica em api.stalwart.it/console. Três formas de entrar, uma única sessão:
- o Google, com o mesmo endereço verificado com que você se cadastrou;
- um link por e-mail, válido por quinze minutos para um login;
- uma chave de API de produção, colada na página. Ela é verificada como a API a verifica e nunca é guardada. Uma chave de teste não consegue entrar: uma chave de teste é a credencial mais fraca, e deixá-la gerenciar as suas chaves de produção a tornaria a mais forte.
Uma pessoa que pertence a várias organizações escolhe uma depois de entrar. A sessão é um único cookie que dura doze horas; Sair a encerra em todo lugar de uma vez. Uma sessão aberta com uma chave relê essa chave a cada requisição, então revogar a chave encerra as suas sessões no console em até um minuto. Toda falha de login mostra a mesma página com a mesma frase, seja qual for a causa, para não dizer a ninguém que esteja tentando adivinhar qual parte do palpite manter.
As páginas¶
As capturas e os nomes das páginas aparecem como o console os mostra, em inglês, até o console ser traduzido.
| Página | O que mostra e faz | Explicada em |
|---|---|---|
| Account | o nome e o plano da sua organização, os seus membros e os seus papéis; convidar por e-mail, mudar um papel, remover um membro, fechar a organização | este capítulo |
| Keys | criar, renomear, trocar e revogar chaves; as permissões de cada chave; uma chave criada é mostrada uma única vez, aqui | abaixo |
| Usage | cada medidor deste mês contra o seu teto, por dia; acertos de cache e os segundos de resolução que eles pouparam | capítulo 16 |
| Billing | só proprietários: o seu plano, o seu preço e moeda, o cartão como o Stripe o descreve, a próxima cobrança, as faturas com os seus PDFs, qualquer carência; assinar, mudar o intervalo ou o cartão, cancelar | capítulo 40 |
| Catalogue | o seu catálogo mais recente com os seus avisos, leituras e escritas marcadas; as suas versões, e restaurar uma | capítulo 21 |
| Rules | a planilha de regras, compilada e verificada na página; salvá-la como uma nova versão do catálogo | capítulo 41 |
| Outcome phrasings | como o resultado de cada escrita é contado ao usuário | capítulo 42 |
| Reply rules | dados pessoais por classe, frases que nunca devem ser ditas, as ofertas que uma resposta pode fazer, o que deve acompanhar uma escrita ou uma citação | capítulo 43 |
| Feedback | os polegares para cima e para baixo dos últimos trinta dias, pelo que receberam a avaliação; só contagens | capítulo 25 |
| Vocabulary | as versões do seu vocabulário e o que o registro de cada uma diz; voltar à anterior | capítulo 25 |
| Miner | as execuções do minerador hospedado, cada uma aplicada ou nomeando a verificação que a segurou | capítulo 25 |
| Accuracy | o conjunto de avaliação escrito a partir do seu catálogo, pontuado, ao lado dos polegares dos seus usuários | capítulo 25 |
| Grammar | as formas de frase que os seus usuários usaram e que o seletor não conseguiu ler, e quais já foram lançadas | capítulo 25 |
| Findings | os projetos, as varreduras e os achados do caçador de bugs, e as suas decisões sobre eles | capítulo 28 |
| Jobs, Service, Storage | os jobs recentes como metadados; as filas; os seus artefatos guardados, e qualquer retenção sobre um deles | capítulos 9 e 16 |
| Settings | ir_only, a retenção do feedback, o que um turno ilegível faz, o compositor de respostas e a recuperação |
capítulos 20 e 44 |
| Administrative history | só proprietários: todo login e toda mudança, só acrescentados | este capítulo |
O console não mostra conteúdo do solver nem conversa. Uma política, um certificado, um patch, um turno de usuário ou uma resposta de agente nunca chegam a uma página; as páginas de feedback e de precisão são contagens. A única exceção é deliberada: um achado do caçador de bugs é o produto, então as páginas Findings o mostram. As conversas dos seus agentes, as suas chamadas de ferramenta e os documentos de que eles respondem ficam na sua própria máquina, então nenhuma página daqui conseguiria mostrá-los.
O que você digita é lido antes de ser enviado. A planilha de regras, as frases de resultado, as regras de resposta e uma nota sobre um achado são conferidas no seu navegador em busca de endereços de e-mail, números de telefone, números de cartão, IBANs, números do National Insurance do Reino Unido e números de CPF. Um formulário com uma ocorrência não é enviado, e a página nomeia o tipo e o campo, nunca o valor.
Toda mudança é auditada, com quem a fez, de onde e quando, e nada muda por um link: toda mudança é um formulário enviado a partir da página.
Quem pode fazer o quê¶
| Proprietário (owner) | Administrador (admin) | Leitor (viewer) | |
|---|---|---|---|
| Ver todas as páginas | sim | sim | sim |
| Criar, renomear, trocar e revogar chaves | sim | sim | não |
| Configurações, catálogo, regras, frases, regras de resposta, voltar o vocabulário | sim | sim | não |
Decidir sobre um achado (com hunt_details) |
sim | sim | não |
| O histórico administrativo | sim | não | não |
| Cobrança, membros, renomear e fechar a organização | sim, conectado como pessoa | não | não |
O papel de uma pessoa vem da sua participação na organização. Uma sessão aberta com uma chave é de administrador, seja quem for que criou a chave: uma chave é uma credencial, não uma pessoa, então ela nunca tem o que só uma pessoa pode fazer, que é a cobrança, os membros e fechar a organização.
Chaves¶
Uma chave tem esta forma:
qls_live_7Kd3nQ9x R2mV… the prefix, an 8-character public id, then 43 characters of secret
qls_test_… the same shape, held to the fast profile
ou seja, o prefixo, um id público de 8 caracteres e 43 caracteres de segredo; a chave de teste tem a mesma
forma e fica restrita ao perfil fast. Ela é enviada como Authorization: Bearer qls_live_…. O cliente a
lê de QLS_API_KEY.
- Uma chave é mostrada uma única vez, quando é criada, e nunca mais por ninguém, nem por nós. Nós só guardamos um hash de mão única dela, então não há nada para mostrar. Guarde-a no seu cofre de segredos, nunca num arquivo que você versiona.
- Chaves de produção e de teste. Uma chave de teste funciona como uma de produção restrita ao perfil
fast, e é recusada na fila de florestas: recusada em vez de rebaixada em silêncio, porque um pedido de prova rebaixado responderia com um veredito sem certificado. - O que uma chave pode fazer é definido pelo seu plano, e mostrado na página Keys só para leitura. O
console não consegue ampliar uma chave além do seu plano.
GET /v1/capabilitiesresponde à mesma pergunta pela API. Uma chave pode ser criada mais restrita que o seu plano, nunca mais ampla. - Toda falha de autenticação é a mesma falha: um cabeçalho ausente, uma chave malformada, uma
desconhecida ou revogada, uma além do prazo da sua troca. Um único
401, uma única mensagem.
Trocando¶
Trocar cria uma substituta, a liga à chave antiga e mantém a antiga funcionando por uma janela que você escolhe: na hora, 24 horas ou 7 dias. O padrão é 24 horas, porque uma troca que quebra a produção na hora é uma troca que ninguém faz. Na hora é a resposta a uma chave vazada, para que aposentar uma chave no prazo e conter um vazamento sejam a mesma ação.
Revogando¶
Revogar para uma chave em até um minuto em todo lugar, encerra as sessões do console que ela abriu e desconecta em até 15 segundos qualquer stream que ela mantenha. Um membro sempre pode revogar a chave da sua própria sessão.
Quando uma chave vaza¶
Troque-a na hora, na página Keys: a chave vazada para dentro de um minuto, e a sua substituta lhe é mostrada uma vez. Depois veja o último uso da chave na página Keys, e o Administrative history, em busca de qualquer coisa que você não fez.
Quando todas as chaves se perdem¶
Entre como pessoa, com o Google ou com um link por e-mail, e crie uma nova chave na página Keys. Só uma
organização que também perdeu o acesso de todos os membros, de modo que ninguém consegue entrar, escreve
para newaccounts@stalwart.it.
Colando uma chave na referência da API¶
A referência da API deixa você testar qualquer operação com a sua própria chave. Ela é pública e não precisa de chave para ser lida; só é preciso uma chave para enviar uma requisição. O que a página faz com a sua chave:
- Uma requisição feita pela página é uma chamada real: autenticada, limitada e medida contra a cota da sua chave como qualquer outra. Nunca é um sandbox nem um modo de teste, e não é gratuita.
- A chave vai para o host que serviu a página e para nenhum outro lugar. O único servidor da página é a sua própria origem, e a política de segurança dela só a deixa fazer requisições para essa origem.
- A página não guarda chave nenhuma no armazenamento do seu navegador, não carrega nada de terceiros e não envia telemetria.
Se você preferir não colar uma chave de produção, crie uma para esse fim na página Keys e revogue-a depois (capítulo 18).
Os limites¶
- O console não consegue ampliar uma chave além do seu plano, não consegue mostrar uma chave de novo e não mostra conteúdo do solver.
- Uma chave é uma credencial: uma sessão aberta com uma delas nunca consegue gerenciar a cobrança ou os membros.
- A revogação tem efeito em até um minuto, não no instante em que você clica.