Server Provider Authentication Guide

This guide explains how server hosting providers can authenticate Hytale dedicated servers.

TL;DR

For Game Server Providers and server network operators wanting automatic 0-click server authentication for up-to 500 servers:

1. Obtain tokens once - Use the Device Code Flow to authenticate and get a refresh_token
2. Create sessions - Call /my-account/get-profiles then /game-session/new to get sessionToken and identityToken

3. Pass tokens to servers - Start each server instance with:

   java -jar HytaleServer.jar \
     --session-token "<sessionToken>" \
     --identity-token "<identityToken>"

   Or via environment variables: HYTALE_SERVER_SESSION_TOKEN and HYTALE_SERVER_IDENTITY_TOKEN

4. Refresh before expiry - 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. Each OAuth refresh issues both a new access token and a new refresh token, invalidating the previous refresh token. The server stays authenticated indefinitely as long as it remains online. Re-authentication is only required if the server is offline for longer than the refresh token TTL (30 days).

Your provisioning system handles token management centrally, so customers never see an auth prompt.

Hytale Downloader CLI

For automating server file downloads and updates, use the Hytale Downloader CLI. This tool handles OAuth2 authentication and can be integrated into your provisioning pipelines to keep server installations current.

Download: hytale-downloader.zip (Quickstart + Linux & Windows)

See Server Manual: Hytale Downloader CLI for full usage documentation.

Overview

Server authentication uses OAuth 2.0 to obtain tokens that authorize the server to:

1. Create game sessions for the server operator's profile
2. Validate players joining the server
3. Access game assets and version information

The server uses the pre-configured hytale-server OAuth client:

Client ID: hytale-server
Scopes: openid, offline, auth:server

OAuth Endpoints

All endpoints follow standard OAuth 2.0 specifications (RFC 6749, RFC 8628).

Authentication Methods

Method A: Server Console Commands (Interactive)

For servers with console access, use built-in authentication commands:

Example workflow:

> /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

Method B: Device Code Flow (RFC 8628)

For automated or headless setups where you need to obtain tokens programmatically.

Step 1: Request Device Code

curl -X POST "https://oauth.accounts.hytale.com/oauth2/device/auth" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=hytale-server" \
  -d "scope=openid offline auth:server"

Response:

{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "ABCD-1234",
  "verification_uri": "https://accounts.hytale.com/device",
  "verification_uri_complete": "https://accounts.hytale.com/device?user_code=ABCD-1234",
  "expires_in": 900,
  "interval": 5
}

Step 2: Display Instructions to User

Show the user:

• URL: verification_uri or verification_uri_complete
• Code: user_code (if using verification_uri)

Step 3: Poll for Token

Poll the token endpoint at the specified interval (default 5 seconds):

curl -X POST "https://oauth.accounts.hytale.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=hytale-server" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  -d "device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS"

Pending response (user hasn't authorized yet):

{
  "error": "authorization_pending"
}

Success response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "xreEsdDGrfIaQc...",
  "scope": "openid offline auth:server"
}

Step 4: Get Available Profiles

curl -X GET "https://account-data.hytale.com/my-account/get-profiles" \
  -H "Authorization: Bearer <access_token>"

Response:

{
  "owner": "550e8400-e29b-41d4-a716-446655440000",
  "profiles": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "username": "ServerOperator"
    }
  ]
}

Step 5: Create Game Session

curl -X POST "https://sessions.hytale.com/game-session/new" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"uuid": "123e4567-e89b-12d3-a456-426614174000"}'

Response:

{
  "sessionToken": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "identityToken": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-01-07T15:00:00Z"
}

The sessionToken and identityToken are what the server uses for authentication.

Method C: Token Passthrough (Environment/CLI)

For hosting providers who manage token acquisition externally and pass tokens to the server at startup.

Environment Variables

CLI Options

Example:

./hytale-server \
  --session-token "eyJhbGciOiJFZERTQSIs..." \
  --identity-token "eyJhbGciOiJFZERTQSIs..." \
  --owner-uuid "123e4567-e89b-12d3-a456-426614174000"

Or via environment:

export HYTALE_SERVER_SESSION_TOKEN="eyJhbGciOiJFZERTQSIs..."
export HYTALE_SERVER_IDENTITY_TOKEN="eyJhbGciOiJFZERTQSIs..."
./hytale-server

The server automatically refreshes game sessions 5 minutes before expiry when in EXTERNAL_SESSION mode. See Token Lifecycle for details on the refresh strategy.

Method D: Credential Store API (Plugin/Programmatic)

For hosting providers who want to programmatically manage credentials and persist tokens across server restarts via plugins.

Interface

public interface IAuthCredentialStore {
    record OAuthTokens(
        @Nullable String accessToken,
        @Nullable String refreshToken,
        @Nullable Instant accessTokenExpiresAt
    ) {}

    void setTokens(@Nonnull OAuthTokens tokens);
    @Nonnull OAuthTokens getTokens();

    void setProfile(@Nullable UUID uuid);
    @Nullable UUID getProfile();

    void clear();
}

Usage

1. Implement IAuthCredentialStore to persist tokens (e.g., database, file, external service)
2. Register before authentication: ServerAuthManager.getInstance().registerCredentialStore(store)
3. Server automatically retrieves and refreshes tokens via the store
4. Auth mode becomes OAUTH_STORE

Key Behaviors

• Registration timing: Store must be registered before any authentication occurs
• Token retrieval: Server calls getTokens() when OAuth tokens are needed
• Token persistence: Server calls setTokens() after successful token refresh
• Profile selection: If getProfile() returns a UUID, that profile is auto-selected

Game Session API Reference

Create Session

Creates a new game session for a specific profile.

Request:

POST /game-session/new
Host: sessions.hytale.com
Authorization: Bearer <oauth_access_token>
Content-Type: application/json

{"uuid": "123e4567-e89b-12d3-a456-426614174000"}

Response (200):

{
  "sessionToken": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "identityToken": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-01-07T15:00:00Z"
}

Get Profiles

Fetches available game profiles for the authenticated account.

Request:

GET /my-account/get-profiles
Host: account-data.hytale.com
Authorization: Bearer <oauth_access_token>

Response (200):

{
  "owner": "550e8400-e29b-41d4-a716-446655440000",
  "profiles": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "username": "ServerOperator"
    }
  ]
}

Refresh Session

Refreshes the current game session to extend its lifetime. Returns new session and identity tokens with a fresh expiry.

Request:

POST /game-session/refresh
Host: sessions.hytale.com
Authorization: Bearer <session_token>

Response (200):

{
  "sessionToken": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "identityToken": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-01-07T16:00:00Z"
}

Terminate Session

Ends the current session (call on server shutdown).

Request:

DELETE /game-session
Host: sessions.hytale.com
Authorization: Bearer <session_token>

Response: 204 No Content

Refresh OAuth Token

Exchange a refresh token for new OAuth tokens. Both the access token and refresh token are rotated. The response includes a new refresh token that replaces the old one.

Request:

curl -X POST "https://oauth.accounts.hytale.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=hytale-server" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=<refresh_token>"

Response (200):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "xyzNewRefreshToken...",
  "scope": "openid offline auth:server"
}

Important: The refresh_token in the response is a new refresh token. You must store it and use it for the next refresh. The previous refresh token is invalidated.

Token Lifecycle

Refresh Strategy

The server schedules an automatic refresh 5 minutes before game session expiry. The refresh process follows this order:

1. Game session refresh: Call POST /game-session/refresh using the current session token. This returns new session and identity tokens with a fresh 1-hour expiry.
2. OAuth fallback: If game session refresh fails, the server refreshes its OAuth tokens using the refresh token, then creates a new game session.

Token Rotation

When refreshing OAuth tokens, the authorization server issues both a new access token and a new refresh token. The previous refresh token is invalidated. This means:

• 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.

Error Handling

Common HTTP Errors

Session Limit Errors

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

Token Validation Errors

The server validates tokens at startup. If validation fails:

Token validation failed. Server starting unauthenticated.
Use /auth login to authenticate.

Common causes:

• Expired tokens
• Invalid token signature
• Missing required scope (hytale:server)

JWKS Endpoint

Servers validate player JWTs using the public keys from:

GET /.well-known/jwks.json
Host: sessions.hytale.com

Response:

{
  "keys": [
    {
      "kty": "OKP",
      "alg": "EdDSA",
      "use": "sig",
      "kid": "key-id-1",
      "crv": "Ed25519",
      "x": "base64url-encoded-public-key"
    }
  ]
}

References

• RFC 6749 - OAuth 2.0 Authorization Framework
• RFC 8628 - OAuth 2.0 Device Authorization Grant
• RFC 7636 - PKCE (Proof Key for Code Exchange)