Referência API
Autenticar no Tungsto API atual
Compreenda o contrato suportado de cookies de sessão e CSRF antes de integrar com os endpoints de conta, faturação e servidores.
Nesta página
Antes de começar
- Uma conta existente e acesso ao serviço de conta em execução através de HTTPS.
- Um cliente que preserva cookies de sessão entre pedidos.
- Para alterações, o token CSRF associado à mesma sessão ativa.
Use o método de autenticação suportado
As rotas protegidas API usam a sessão de conta estabelecida no início de sessão. O cookie de sessão chama-se __Host-tungsto-session e está marcado como Secure e HttpOnly. Um segundo cookie, __Host-tungsto-csrf, suporta a verificação de pedidos. As alterações de conta requerem um cabeçalho x-csrf-token correspondente a essa sessão, além do cookie de sessão.
O ecrã de chaves SSH e API cria, lista e revoga chaves com âmbitos definidos. Envie Authorization: Bearer seguido da chave de utilização única. O âmbito de leitura permite GET /api/v1/servers, detalhes do servidor e /api/v1/orders. O âmbito de servidores permite servidores, detalhes do servidor e /api/v1/network. O âmbito de faturação permite GET /api/v1/ledger.. Todas as mutações de chaves API são negadas, mesmo que uma sessão de navegador também esteja presente. Uma alteração de palavra-passe ou recuperação de conta revoga as chaves existentes. Não construa automação de hardware de produção ou de pagamentos sem supervisão em torno desta pré-visualização local.
Estabelecer e verificar uma sessão
O pedido acima mostra apenas nomes de campos. Forneça credenciais de forma segura no seu próprio cliente; não guarde uma palavra-passe real em exemplos partilhados ou saídas de diagnóstico. Os pedidos de um navegador devem permanecer no mesmo site. Um cabeçalho Origin que indique outra origem é rejeitado.
- Envie um POST JSON para /api/v1/auth/login contendo nome de utilizador e palavra-passe. Guarde os valores Set-Cookie devolvidos por uma resposta bem-sucedida no armazenamento protegido de cookies do cliente.
- Mantenha o csrfToken devolvido na resposta JSON com essa sessão. Não misture um token de um início de sessão com cookies de outro.
- Chame GET /api/v1/me com os cookies para verificar a conta. A resposta contém o nome de utilizador, o balanceUsd e o csrfToken.
- Para uma alteração protegida, envie os cookies de sessão, Content-Type: application/json e x-csrf-token. Inclua um Idempotency-Key quando o endpoint o exigir.
- Termine a sessão utilizando POST /api/v1/auth/logout quando o cliente tiver terminado.
POST /api/v1/auth/login HTTP/1.1
Content-Type: application/json
{"username":"your-username","password":"your-password"}Lidar com expiração de sessão e erros de verificação
Uma recuperação de conta bem-sucedida altera a palavra-passe, revoga as sessões existentes e emite um código de recuperação de substituição. Os clientes que utilizem cookies anteriores têm de se autenticar novamente. O serviço também expira as sessões, pelo que uma ligação anteriormente bem-sucedida não é uma credencial ilimitada.
| Resposta | Significado | Próxima ação |
|---|---|---|
| 401 authentication_required | Não foi encontrada nenhuma sessão de conta válida. | Inicie sessão novamente e mantenha os novos cookies. |
| 401 session_invalid | O cookie de sessão e o CSRF não verificam em conjunto. | Inicie um novo início de sessão em vez de reutilizar cookies misturados. |
| 403 csrf_failed | O pedido de alteração não contém o token de verificação correspondente. | Recarregue as informações da sessão e use o seu token atual. |
| 403 origin_rejected | A Origem fornecida é diferente da origem do pedido. | Execute o pedido a partir do contexto suportado do mesmo site. |
| 429 rate_limited | Foram feitas demasiadas tentativas de autenticação. | Aguarde antes de tentar novamente; não repita continuamente. |
Mantenha a integração dentro do contrato atual
O ecrã de Segurança lista as sessões ativas através de GET /api/v1/sessions e revoga uma sessão própria através de DELETE /api/v1/sessions/:id.. O ecrã de chaves lista e revoga chaves API. Não existe fluxo OAuth. O registo e a recuperação são operações interativas de acesso à conta, não substitutos de um mecanismo de conta de serviço. Evite distribuir os cookies de sessão de uma pessoa por várias ferramentas ou utilizadores.
Receber sucesso de autenticação confirma o acesso à conta, não que todas as operações externas estão disponíveis. A liquidação em criptomoeda precisa de um fornecedor ligado; ações físicas no servidor precisam que o operador execute pedidos em fila. Leia o guia de operações para resultados específicos de cada endpoint e comportamento de repetição antes de interpretar uma resposta bem-sucedida como uma ação real concluída.