Hytale Server Authentication: Why It Asks You to Log In Again, What auth.enc Does, and Every Error Decoded

A Hytale server that will not stay authenticated is one of the most common things server owners ask about, and the explanations circulating on host knowledge bases and forum threads do not always agree with each other. This guide sticks to what Hytale actually documents. Two official sources are used throughout: the Hytale Server Manual on support.hytale.com, last updated 15 June 2026, and the Server Provider Authentication Guide on the same site, last updated 10 March 2026. Where something is our inference rather than documentation, this guide says so. Where a popular claim is not documented, it says that too, in the final section. The Short Answer There are two completely different problems that both look like "my server keeps asking me to log in", and they have different fixes. You re-authenticate after every restart. That is credential storage. Your credentials are being held in memory and lost on shutdown. Fix it with /auth persistence. You re-authenticate after a long period switched off. That is the refresh token expiring. The documented lifetime is 30 days of being unused, and there is no way around it other than logging in again. Everything below expands on those two cases. How Hytale Server Authentication Works The Server Provider Authentication Guide describes the mechanism directly: Server authentication uses OAuth 2.0 to obtain tokens that authorize the server to: Create game sessions for the server operator's profile Validate players joining the server Access game assets and version information So authentication is not only about proving the server exists. It is also what lets the server validate the players who connect to it, which is why an unauthenticated server is not merely inconvenienced. The refresh behaviour is the part that answers the most questions: A running server stays authenticated indefinitely. Each refresh extends the refresh token's 30-day TTL, so the token never expires as long as the server keeps refreshing. Re-authentication is only required if the server is offline for more than 30 days. If the refresh token expires without being used (i.e., the server was down for 30+ days), a user must re-authenticate via /auth login or by providing new tokens. The guide also documents the shorter cycle underneath it: Game sessions expire in 1 hour and are auto-refreshed 5 minutes before expiry. If game session refresh fails, the server falls back to OAuth token refresh. That is the whole model. An hourly game session that renews itself, sitting on top of a 30-day refresh token that renews every time it is used. A server left running looks after itself. A server parked for a month does not. This is worth knowing in advance if you are bringing a dormant server back for a launch. A box that has been off since the summer will need authenticating again before players can join, and that is a five-minute job you would rather not discover on the day. Authenticating a Server for the First Time The Server Manual's instruction after first launch is simply /auth login device, and it shows the resulting console output: > /auth login device =================================================================== DEVICE AUTHORIZATION =================================================================== Visit: https://accounts.hytale.com/device Enter code: ABCD-1234 Or visit: https://accounts.hytale.com/device?user_code=ABCD-1234 =================================================================== Waiting for authorization (expires in 900 seconds)... [User completes authorization in browser] > Authentication successful! Mode: OAUTH_DEVICE The manual adds: "Once authenticated, your server can accept player connections." The 900 seconds in that output is the device code lifetime, so there is no rush but there is a deadline. If it lapses, run the command again for a fresh code. The Full /auth Command Reference The Server Provider Authentication Guide lists the console commands with these descriptions: /auth login device Start device code flow (recommended for headless servers) /auth login browser Start browser PKCE flow (requires desktop environment) /auth select Select a game profile when multiple are available /auth status Check current authentication status /auth cancel Cancel an in-progress authentication flow /auth logout Clear authentication and terminate session /auth persistence View current credential storage method /auth persistence with a value Change credential storage method (Memory or Encrypted) Two of those deserve emphasis. /auth login browser "requires desktop environment", so on a headless box the device flow is the one that works, which is exactly why the documentation recommends it there. And /auth logout does not just forget your credentials, it terminates the session, so it is not a harmless command to try while players are connected. Credential Storage, and the Restart Problem If you authenticate successfully and then find yourself doing it again after every restart, the storage method is the thing to check. The documented choice is between Memory and Encrypted, set through /auth persistence. Run /auth persistence on its own to see which one is active. The names describe the behaviour: credentials held in memory do not outlive the process. The Server Manual shows where the encrypted credentials live. Describing the layout produced by a bootstrap install, it says the installer "migrates auth.enc, auth.key, and config.json into Server/" and prints the resulting directory tree: game/ ├── Assets.zip ├── start.sh ├── start.bat └── Server/     ├── HytaleServer.jar     ├── auth.enc     ├── auth.key     └── config.json It then notes that "The credentials from step 2 are carried over, so the server is authenticated on first boot." So there are two files, not one: auth.enc and auth.key. The manual does not describe the internals of either, and this guide will not speculate about them. What follows from the documentation is practical enough. Both files belong to your server's identity, so they need to be present together for stored credentials to be usable, they need to move together if you migrate the server, and they are credentials rather than configuration, so they do not belong in a public repository or a shared backup that other people can read. Our inference, clearly labelled as such: if you are running the server in a container or under any setup that starts from a clean directory each time, credentials written to disk are only durable if that directory is genuinely persistent. The documentation does not discuss containers, and we have not tested this. --auth-mode and What the Default Is The Server Manual's --help output includes the line: --auth-mode Authentication mode (default: AUTHENTICATED) That is the full extent of what the manual documents about it: the flag exists, and the default is AUTHENTICATED. The manual's own help listing does not enumerate the other accepted values, and rather than guess at them from third-party sources, this guide leaves it there. If you have not passed the flag, you are on the default, which is the mode you want for a public server that validates its players. Reading the Errors The documented failure at startup has specific wording. The Server Provider Authentication Guide says the server validates tokens at startup and, if validation fails, prints: Token validation failed. Server starting unauthenticated. Use /auth login to authenticate. It lists the common causes as: Expired tokens Invalid token signature Missing required scope (hytale:server) Note what that message means in practice. The server does not refuse to boot. It starts anyway, unauthenticated, which is why an owner can have a server that appears to be running perfectly while players cannot join it properly. If you are diagnosing a server that is up but wrong, this line is the one to search the log for. For HTTP-level failures against the account APIs, the guide documents these statuses: 400 Bad Request Invalid request format or missing required fields 401 Unauthorized Missing or invalid authentication 403 Forbidden Valid auth but insufficient permissions (missing entitlement, session limit) 404 Not Found Resource not found (invalid profile UUID, etc.) The 403 is the interesting one, because "valid auth but insufficient permissions" is easy to misread as a broken login when it is not. The 500 Session Limit If you run many servers, there is a documented ceiling. The Server Provider Authentication Guide states: Accounts are limited to 500 concurrent server sessions. Attempting to create more returns a 403 Forbidden error. If you require additional server sessions, please reach out to our support team here The Server Manual states the same limit from the licence angle: Note: There is a limit of 500 servers per Hytale game license to prevent early abuse. If you require additional capacity, please reach out to our support team here. Both put the number at 500 and both point at support for more. We mention this explicitly because a lower figure circulates in third-party guides, and the official documentation says 500 in two separate places. If you hit a 403 while creating sessions at scale, the limit is the documented cause and support is the documented route past it. Headless and Automated Setups For provisioning many servers, the documentation describes passing tokens in rather than logging in on each box. The guide's summary of the flow is to obtain tokens once through the device code flow, call /my-account/get-profiles and then /game-session/new to get a sessionToken and an identityToken, and start each server with them: java -jar HytaleServer.jar \   --session-token "" \   --identity-token "" It adds that this can be done "via environment variables: HYTALE_SERVER_SESSION_TOKEN and HYTALE_SERVER_IDENTITY_TOKEN", and that with central token management "customers never see an auth prompt". There is also a plugin-level route. The guide documents an IAuthCredentialStore interface you can implement "to persist tokens (e.g., database, file, external service)", registered with ServerAuthManager.getInstance().registerCredentialStore(store), noting that the "Store must be registered before any authentication occurs" and that the auth mode then "becomes OAUTH_STORE". That is aimed at hosting providers rather than someone running one server, but it is the documented answer to storing credentials somewhere other than local disk. A Short Troubleshooting Order Our suggested sequence, built from the documented behaviour above. Run /auth status first. It is the documented way to see where you actually stand, and it costs nothing. Search the log for "Server starting unauthenticated". If it is there, the server booted without valid tokens and the cause is one of the three documented ones. If the problem happens on every restart, run /auth persistence. Memory storage does not survive a restart by design. If the server has been off for a long time, just log in again. Past 30 days unused, the refresh token is gone and re-authentication is the documented requirement, not a bug. If you moved or rebuilt the server, check auth.enc and auth.key came with it. They sit next to config.json in the Server directory. On a headless box use /auth login device. The browser flow is documented as requiring a desktop environment. If you are getting 403 at scale, check the 500 session limit before assuming your credentials are wrong. If players cannot connect but your server is authenticated, the problem is probably elsewhere: our guides on failed to connect errors and domains and ports cover the networking side, and crash recovery covers a server that will not stay up at all. Claims We Could Not Verify Several assertions about Hytale authentication are repeated widely and do not appear in either official document. We are not saying they are false. We are saying they are not documented, and we did not test them, so this guide does not present them as fact. A system clock more than 60 seconds off causing token failures. Neither document mentions clocks, skew or time synchronisation. Keeping server clocks accurate is sound practice regardless, but we cannot cite an official source for that specific threshold. A per-account limit lower than 500. Both official documents say 500. Persistent machine identifiers. Neither document mentions a machine ID. The full list of --auth-mode values. The manual documents the default and nothing more. If any of these are formalised later, the Server Manual and the Server Provider Authentication Guide are where it will appear, and both carry a last-updated date worth checking. The Bottom Line Hytale server authentication is better documented than its reputation suggests. A running server refreshes itself forever. A server offline for over 30 days has to log in again, by design. A server that forgets its credentials on every restart is storing them in memory, and /auth persistence is the documented switch. With Chapter 1 arriving on 12 October, the case worth acting on now is the dormant one. If your server has been switched off for a while, start it and run /auth status this week rather than on launch day. Our Chapter 1 preparation checklist covers the rest, and the server setup guide covers a build from scratch. Server authenticated and ready? List it on HytaleCharts so players can find it.