Create a hosted verification form

A plugin can create a one-time hosted form and receive its submission inside the agent JVM. Use this for plugin-owned forms, then apply your own authorization policy.

For game-account sign-in and tokens, use Game OAuth. A hosted form does not issue an OAuth token or independently prove a player's Microsoft identity.

Before you beginCopy Anchor Link

You need a supported game agent, its plugin API dependency, and a plugin lifecycle that manages coroutine work and shutdown. Challenge creation needs a live authenticated agent connection.

The API is experimental. Kotlin callers must opt in. Java callers must account for the Kotlin suspend-function boundary; the example below uses Kotlin directly.

Register and create a formCopy Anchor Link

The following class is complete against the current API. Call begin() from your plugin's coroutine scope after the agent loads. Give the returned URL to the intended player through your platform's messaging API.

import com.enderdash.agent.api.EnderdashApi
import com.enderdash.agent.api.ExperimentalEnderdashApi
import com.enderdash.agent.api.verification.VerificationChallengeCreateRequest
import com.enderdash.agent.api.verification.VerificationChallengeValidationResult
import com.enderdash.agent.api.verification.VerificationFieldSpec
import com.enderdash.agent.api.verification.VerificationFieldType
import java.util.concurrent.ConcurrentHashMap

@OptIn(ExperimentalEnderdashApi::class)
class HostedVerification(private val api: EnderdashApi) : AutoCloseable {
    private val pending = ConcurrentHashMap<String, String>()
    private val registration = api.verification.registerValidationHandler("example-plugin") { event ->
        val expectedPlayer = pending[event.challengeId]
        val response = event.fields["reply"]?.values?.singleOrNull()?.trim()
        when {
            expectedPlayer == null || event.playerUuid != expectedPlayer ->
                VerificationChallengeValidationResult.rejected("unknown_challenge", "Request not found")
            !event.risk.hcaptchaPassed ->
                VerificationChallengeValidationResult.rejected("captcha_failed", "Complete the captcha")
            response.isNullOrEmpty() || response.length > 100 ->
                VerificationChallengeValidationResult.rejected("invalid_reply", "Enter 1 to 100 characters")
            else -> {
                pending.remove(event.challengeId)
                VerificationChallengeValidationResult.accepted("Response received")
            }
        }
    }

    suspend fun begin(playerUuid: String): String {
        val challenge = api.verification.createChallenge(
            VerificationChallengeCreateRequest(
                pluginId = "example-plugin",
                title = "Send a response",
                playerUuid = playerUuid,
                fields = listOf(
                    VerificationFieldSpec(
                        id = "reply",
                        type = VerificationFieldType.TEXT,
                        label = "Response",
                        minLength = 1,
                        maxLength = 100,
                    ),
                ),
                expiresInSeconds = 300,
            ),
        )
        pending[challenge.challengeId] = playerUuid
        return challenge.url
    }

    override fun close() {
        registration.close()
        pending.clear()
    }
}

This example validates a form response. It does not grant privileges. In a real plugin, also check your local operation state, expiration, and correlation before applying any protected change. Remove expired entries from the pending map.

Close the class from your plugin's shutdown callback and cancel plugin-owned coroutine work. Register only one handler per plugin ID. Creation can throw when signaling is unavailable or the request is rejected.

Verify the complete flowCopy Anchor Link

1. Register the handler after retrieving the active API provider.
2. Create a challenge for a test player and open its returned URL.
3. Complete hCaptcha and submit a short response.
4. Confirm the handler accepted the expected challenge.
5. Check the server's Verification panel for the result and decision code.
6. Test an invalid response, an expired challenge, and plugin shutdown before allowing protected operations.

A null handler result or a thrown exception rejects the submission as unhandled. Always return an explicit accepted or rejected result.

Form limitsCopy Anchor Link

A challenge contains 1 to 8 fields. Its default lifetime is 300 seconds; the maximum is 900 seconds.

Field IDs are the keys in the handler's submitted-field map. Validate required fields again in the handler instead of relying only on browser validation.

Risk metadata and cancellationCopy Anchor Link

The event includes hCaptcha status and network classifications such as proxy, hosting, and mobile. Geographic enrichment is best effort and nullable. Treat those classifications as policy inputs, not a complete trust decision.

Cancel a pending challenge with api.verification.cancelChallenge(challengeId). A true result means the control plane accepted the cancellation. False can mean the challenge completed, expired, or was unknown.

Next: API lifecycle and lookups or Game OAuth for identity sign-in.