Autenticação

Credenciais PMS: formato, ambientes, armazenamento seguro, rotação e revogação.

Cada pedido, exceto GET /v1/health, leva a sua credencial PMS como token Bearer:

GET /v1/me HTTP/1.1
Host: staging.api.tatallo.com
Authorization: Bearer tat_stg_sk_<credential-id>_<secret>

Não há troca de tokens nem nada para renovar: a chave em si é a credencial. Uma chave pode ter data de expiração, que a Tatallo indica quando a emite.

​

Formato da chave e ambientes

Uma credencial PMS é uma cadeia opaca emitida pela Tatallo. O prefixo indica o ambiente a que pertence:

Prefixo	Ambiente	Base URL
tat_stg_sk_	Staging	https://staging.api.tatallo.com
tat_live_sk_	Produção	https://api.tatallo.com

Uma chave só funciona no seu ambiente. Uma chave de staging enviada a produção recebe 401, e o mesmo acontece com uma chave de produção em staging, para o tráfego de testes nunca chegar a dados reais. Trate o resto da chave como opaco: não a analise.

​

Mantenha as chaves nos seus servidores

• Chame a API PMS Tatallo apenas servidor a servidor. Nunca envie uma chave para um navegador, uma aplicação móvel ou qualquer outro cliente.
• Guarde as chaves no gestor de segredos, não no código-fonte nem em ficheiros de configuração.
• Nunca escreva uma chave nos logs, nem o cabeçalho Authorization. GET /v1/me nunca devolve um segredo, por isso escrever a resposta nos logs é seguro.
• Se suspeitar que uma chave foi exposta, avise [e-mail] de imediato. A Tatallo revoga-a na hora.

​

Rotação e revogação

Peça a [e-mail] para rodar uma chave. A Tatallo emite primeiro a nova chave, através de uma ligação secreta de utilização única. Mude os servidores para a nova chave e a Tatallo só revoga a antiga quando vir chamadas com a nova, sem tempo de inatividade.

Uma chave revogada ou expirada recebe 401 no pedido seguinte.

​

401 ou 403?

Estado	code	Significado	O que fazer
401	unauthorized	A chave falta, está mal formada, é do outro ambiente, expirou ou foi revogada. Todas recebem a mesma resposta, de propósito.	Verifique o cabeçalho, o prefixo face à base URL e se a chave está atual.
403	insufficient_scope	A chave é válida mas não tem o âmbito que a rota precisa (properties:read para propriedades).	Peça uma chave com esse âmbito.

GET /v1/me mostra os âmbitos da chave que está a usar.