HYAUTHDashboard

Getting Started

Integrate HyAuth into your application in a few simple steps.

1

Sign in to the Dashboard

Go to the Dashboard and sign in with your Hytale account to manage your API keys.

2

Create an API Key

Create a new API key from the dashboard. The key name will be shown to users during authentication.

3

Create an Auth Session

Make a POST request to create an authentication session. You'll receive a session ID and a login URL to redirect users to.

4

Get the Result

Poll the session endpoint to check if the user has completed login. Once complete, you'll receive the requested profile data.

API Reference

Complete reference for the HyAuth authentication API.

POST/api/auth/create

Creates a new authentication session and returns a login URL for the user.

Headers

Authorization: Bearer hy_your_api_key
Content-Type: application/json

Request Body

{
  "scopes": {
    "gameProfiles": true,
    "email": true
  },
  "redirectUrl": "https://yourapp.com/callback"
}

Response

{
  "success": true,
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "loginUrl": "https://www.hyauth.com/login?session=a1b2c3d4...",
  "expiresIn": 599
}
GET/api/auth/{sessionId}

Retrieves the current status and result of an authentication session.

Headers

Authorization: Bearer hy_your_api_key

Response — Pending

{
  "success": true,
  "status": "pending"
}

Response — Completed

{
  "success": true,
  "status": "completed",
  "kratosId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "player@example.com",
  "gameProfiles": [
    {
      "username": "Player123",
      "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "entitlements": ["game.base", "game.deluxe"],
      "skin": "{...}",
      "createdAt": "2025-01-15T12:00:00.000000Z"
    }
  ]
}

Response — Failed

{
  "success": true,
  "status": "failed"
}

Scopes

Scopes define what data your application can access from the user's Hytale account.

gameProfiles

Access the user's game profiles including username, UUID, and skin URL.

emailPrivileged

Access the user's email address. This is a privileged scope and requires approval.

Error Codes

The API uses standard HTTP status codes to indicate the success or failure of a request.

400

Bad Request — Missing or invalid parameters.

401

Unauthorized — Invalid or missing API key.

403

Forbidden — API key does not have access to requested scopes.

404

Not Found — Session ID does not exist.

502

Bad Gateway — Upstream Hytale service unavailable.

Documentation - HyAuth