Reference

Game OAuth

A third-party app can use the EnderDash OAuth issuer to sign in a person who controls a game account. EnderDash supports Minecraft and Hytale accounts.

The issuer uses OpenID Connect with the authorization-code flow.

The issuer runs at https://oauth.enderdash.com. It is separate from the EnderDash dashboard and does not use dashboard accounts.

For sign-in with an EnderDash dashboard account, use Account OAuth. The two providers do not share clients or tokens.

A successful sign-in proves that a player completed the command on a server allowed by the verifier policy. The proof relies on that server's account authentication and reported player identity. It does not independently authenticate the player with Microsoft or Hytale.

Register a client

Each OAuth client belongs to an organization. Owners and admins can create clients.

Open Game OAuth for the organization. Then create a client.

A client has:

Field	Notes
Name	A name for admins. It can contain up to 80 characters.
Redirect URIs	1 to 16 exact callback URLs. Use `https` outside local development. The request `redirect_uri` must match a saved URL after normalization.
Verifier policy	Allow any game server in the organization, or restrict verification to selected servers.

The client does not store scopes. An authorization request can use openid, profile, or both.

Every successful grant contains openid profile.

EnderDash returns a client_id with the edoc_ prefix. It also returns a client_secret with the edos_ prefix.

EnderDash shows the secret only once. Store it in a secure location.

If the secret becomes public, rotate it from the same page.

EnderDash supports the authorization code flow for confidential clients. It also supports PKCE when the client sends a code challenge.

Send the user to /oauth2/authorize with the request parameters.
Tell the user to keep the hosted page open.
Tell the user to join an allowed verifier server.
Tell the user to run /enderdash login <code> in chat.
After the server accepts the command, EnderDash redirects to redirect_uri.
Read the code and original state from the redirect.
Exchange the code at /oauth2/token for an ID token and access token.
Send the access token to /oauth2/userinfo to read the player claims.

Keep the page open

The authorize page waits for the in-game command. After the server accepts the command, the page redirects automatically.

Endpoints

The discovery document is at /.well-known/openid-configuration. Most clients need only the issuer URL.

Endpoint	Method	Purpose
`/.well-known/openid-configuration`	GET	Discovery document.
`/oauth2/jwks`	GET	Keys that validate ID tokens.
`/oauth2/authorize`	GET	Starts the flow and renders the hosted page.
`/oauth2/token`	POST	Exchanges an authorization code for tokens.
`/oauth2/userinfo`	GET	Returns claims for a valid access token.

Supported parameters

Capability	Values
Response types	`code`
Grant types	`authorization_code`
Scopes	`openid`, `profile`
PKCE methods	`S256`, `plain`
Token endpoint auth	`client_secret_basic`, `client_secret_post`

The /oauth2/authorize request requires response_type=code, client_id, redirect_uri, and state.

The request can include scope, nonce, code_challenge, and code_challenge_method. EnderDash gets the organization from the unique client_id.

Claims

The ID token and /oauth2/userinfo response identify the verified player. They do not identify an EnderDash dashboard user.

Claim	Description
`sub`	Stable identifier for the game account within the organization and game.
`preferred_username`	Current game account name.
`game`	Game that owns the account, currently `minecraft` or `hytale`.
`game_account_name`	Current game account name.
`game_account_id`	Game account UUID.
`organization_id`	Organization that owns the OAuth client and allowed verifier servers.
`verified_by_server_id`	Server that completed the in-game proof. This value is not part of `sub`.

Token exchange example

Send a form-encoded request from your backend. Use the same callback URI saved during authorization. Use its normalized form consistently, including a trailing slash when present.

curl 'https://oauth.enderdash.com/oauth2/token' \
  --user '<client-id>:<client-secret>' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=<authorization-code>' \
  --data-urlencode 'redirect_uri=https://example.com/callback' \
  --data-urlencode 'code_verifier=<original-pkce-verifier>'

The response contains access_token, id_token, token_type, expires_in, and scope. token_type is Bearer, expires_in is 900, and scope is openid profile. Omit code_verifier only when the authorization request did not use PKCE. Prefer S256 for new integrations and set code_challenge_method explicitly.

curl 'https://oauth.enderdash.com/oauth2/userinfo' \
  -H 'Authorization: Bearer <access-token>'

Validate the callback state before you exchange its code. Validate the ID token's RS256 signature, issuer, audience, expiration, and original nonce through your OIDC library. Use the issuer and sub together as the account key. Player names can change.

Game tokens do not authenticate the dashboard HTTP API.

Token lifetimes

The hosted authorization session lasts 10 minutes. The returned authorization code lasts 90 seconds and permits one exchange. ID tokens are valid for 10 minutes. Access tokens are valid for 15 minutes.

A failed redirect or PKCE check can consume the authorization code. Start a new flow instead of retrying that code.

The issuer does not provide refresh tokens. Start a new sign-in flow after a token expires.

Troubleshooting

Problem	Check
Return address rejected	Client enabled and callback saved under the organization's Game OAuth page
Security check failed	Browser can reach Cloudflare Turnstile
Server cannot verify the code	Correct organization, allowed server, active challenge, connected agent
Browser does not redirect	Hosted page remains open and its live connection works
`invalid_client`	Game client ID and current game client secret
`invalid_grant`	Code age, prior use, exact callback URI, client ID, and PKCE verifier
`invalid_token`	Access token from this issuer, within its lifetime

Secret rotation and client disablement affect new exchanges. Previously issued access tokens can remain valid until expiration.

Agent Commands for the enderdash login <code> player command.
Access Model for how organization and server roles work.

Was this page helpful?

Send a quick note if anything is missing or unclear.

Last updated on

MCP Server

Tools, inputs, scopes, and access rules for the EnderDash MCP server.

HTTP API

Learn how to authenticate and send requests to the EnderDash HTTP API.

Game OAuth

Was this page helpful?

On this page