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¶
Registre seu interesse na página de registro de interesse do site; nós respondemos com o seu acesso. Você então abre a sua conta na página de acesso do console, com o Google ou com um link enviado por e-mail.
- 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.
Na primeira vez que você entra, a sua organização gratuita é criada para você, com o nome do seu endereço (mude-o em Conta), e você é a proprietária; continuar na página de acesso aceita os termos e o adendo de tratamento de dados, e as versões que você aceitou são registradas. O console de desenvolvedores abre na sua Visão geral. Uma organização não tem chave até você criar uma em Chaves, ou até um bot rodar pela primeira vez: uma chave é mostrada uma única vez, quando é criada, então copie-a nessa hora; 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.
Por trás da página, o site envia o seu endereço a POST /v1/signup, que não precisa de chave e envia o link;
um link de login pedido para um endereço sem conta é enviado como link de cadastro. Passados cinco links por
hora para um endereço, vinte para uma rede ou duzentos para um domínio, a resposta traz um quebra-cabeça de
prova de trabalho, que um navegador resolve em um ou dois segundos; GET /v1/signup/challenge entrega um a
uma página que sabe que vai precisar dele. Cadastrar com o Google é GET /v1/signup/google, que pede ao
Google o seu endereço verificado e nada mais.
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 mantém este navegador conectado por trinta dias desde a última vez que você o usou; 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.
A página de login é /console/login. O seu formulário de e-mail envia para /console/login/email, sob os
mesmos limites do cadastro. O link enviado abre /console/link, uma página com um único botão, e nada é gasto
até você apertá-lo, de modo que um verificador de e-mail que segue o link não faz login de ninguém. Um
navegador a quem se pede antes um quebra-cabeça é levado a /console/challenge. O Construtor de Bots e o
fórum compartilham essa mesma sessão: GET /v1/session diz quem ela identifica, e Sair é
POST /v1/session/end, que a encerra nos três.
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 |
|---|---|---|
| Conta | 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 |
| Chaves | criar, renomear, trocar e revogar chaves; as permissões de cada chave; uma chave criada é mostrada uma única vez, aqui | abaixo |
| Uso | 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 |
| Cobrança | 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 |
| Rules | a planilha de regras, compilada na página; nada é salvo | 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 |
| 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 idioma que o seletor lê e os identificadores da sua própria organização; o que um turno ilegível faz, o compositor de respostas e a recuperação são de cada agente, no agent.yaml |
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… o prefixo, um id público de 8 caracteres, depois 43 caracteres de segredo
qls_test_… a mesma forma, presa ao perfil rápido
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.
A sua chave da Stalwart e a chave do seu modelo¶
São duas chaves fáceis de confundir, e uma nunca substitui a outra:
| A sua chave da Stalwart | A chave do seu modelo | |
|---|---|---|
| Para que serve | tudo o que você faz com a Stalwart: o cliente, o comando stalwart, a API e o console |
chamar o provedor do seu modelo: Anthropic, OpenAI, Google ou outro |
| Onde você a obtém | aqui, na página Keys | no console do próprio provedor |
| Que forma tem | qls_live_… ou qls_test_… |
a que o seu provedor emitir |
| De onde é lida | QLS_API_KEY |
da variável de costume do provedor: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, … |
| O que guardamos dela | um hash de mão única | nada |
A chave do seu modelo nunca é digitada no console, e nunca nos é enviada com as falas dos seus agentes: o seu agente chama o seu modelo da sua própria máquina (capítulo 30). A única chamada que a traz até nós é a escrita de um guardrail, que a leva ao worker e a apaga assim que é lida (capítulo 13).
O id público não é nenhuma das duas. A página Keys lista cada chave pelo seu id público, os 8 caracteres depois do prefixo, que distinguem as suas chaves e não chamam a API. Se a página Keys só lhe mostra ids públicos, é só isso que ela vai mostrar: a chave em si apareceu uma única vez, quando foi criada. Se não foi copiada naquela hora, crie uma nova, ou troque a antiga.
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.