API reference
Authenticate to the current Tungsto API
Understand the supported session-cookie and CSRF contract before integrating with account, billing and server endpoints.
On this page
Before you start
- An existing account and access to the running account service over HTTPS.
- A client that preserves session cookies between requests.
- For changes, the CSRF token associated with the same active session.
Use the supported authentication method
Protected API routes use the account session established by sign-in. The session cookie is named __Host-tungsto-session and is marked Secure and HttpOnly. A second cookie, __Host-tungsto-csrf, supports request verification. Account changes require an x-csrf-token header matching that session, in addition to the session cookie.
The SSH & API keys screen creates, lists and revokes scoped keys. Send Authorization: Bearer followed by the one-time key. The read scope allows GET /api/v1/servers, server detail and /api/v1/orders. The servers scope allows servers, server detail and /api/v1/network. The billing scope allows GET /api/v1/ledger. All API-key mutations are denied, even if a browser session is also present. A password change or account recovery revokes existing keys. Do not build unattended production hardware or payment automation around this local preview.
Establish and verify a session
The request above shows field names only. Supply credentials securely in your own client; do not save a real password in shared examples or diagnostic output. Requests from a browser must stay on the same site. An Origin header naming another origin is rejected.
- Send a JSON POST to /api/v1/auth/login containing username and password. Keep the Set-Cookie values returned by a successful response in the client’s protected cookie store.
- Keep the csrfToken returned in the JSON response with that session. Do not mix a token from one sign-in with cookies from another.
- Call GET /api/v1/me with the cookies to verify the account. Its response contains username, balanceUsd and csrfToken.
- For a protected change, send the session cookies, Content-Type: application/json and x-csrf-token. Include an Idempotency-Key when the endpoint requires it.
- End the session using POST /api/v1/auth/logout when the client has finished.
POST /api/v1/auth/login HTTP/1.1
Content-Type: application/json
{"username":"your-username","password":"your-password"}Handle session expiry and verification errors
A successful account recovery changes the password, revokes existing sessions and issues a replacement recovery code. Clients using earlier cookies must authenticate again. The service also expires sessions, so a previously successful connection is not an unlimited credential.
| Response | Meaning | Next action |
|---|---|---|
| 401 authentication_required | No valid account session was found. | Sign in again and retain the new cookies. |
| 401 session_invalid | The session and CSRF cookie do not verify together. | Start a fresh sign-in instead of reusing mixed cookies. |
| 403 csrf_failed | The change request lacks the matching verification token. | Reload the session information and use its current token. |
| 403 origin_rejected | The supplied Origin is different from the request’s origin. | Run the request from the supported same-site context. |
| 429 rate_limited | Too many authentication attempts were made. | Wait before trying again; do not continuously retry. |
Keep the integration within the current contract
The Security screen lists active sessions through GET /api/v1/sessions and revokes an owned session through DELETE /api/v1/sessions/:id. The keys screen lists and revokes API keys. There is no OAuth flow. Registration and recovery are interactive account-access operations, not substitutes for a service-account mechanism. Avoid distributing one person’s session cookies among multiple tools or users.
Receiving authentication success confirms account access, not that every external operation is available. Crypto settlement needs a connected provider; physical server actions need the operator to execute queued requests. Read the operations guide for endpoint-specific results and retry behavior before interpreting a successful response as a completed real-world action.