> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/apis/apis/auth-server/requests.md).
# Requests
Authentication request management endpoints
## Create authentication request
> Creates a new authentication request that can be executed by the auth dapp.\
> \
> \*\*Important:\*\*\
> \- The \`authChain\` field is \*\*required\*\* and will be validated.\
> \- Signature validation is performed using \`@dcl/crypto\` Authenticator.\
> \- The \`dcl\_personal\_sign\` method is rejected, as is signing a Decentraland ephemeral message\
> under any other method. Ordinary \`personal\_sign\` / \`eth\_sign\` requests are accepted.\
> \- The request will expire after the configured expiration time (default: 5 minutes).
```json
{"openapi":"3.1.0","info":{"title":"Auth Server API","version":"1.0.0"},"tags":[{"name":"Requests","description":"Authentication request management endpoints"}],"servers":[{"url":"https://auth-api.decentraland.org","description":"Production server"},{"url":"https://auth-api.decentraland.zone","description":"Development server"},{"url":"http://localhost:{port}","description":"Local development server (replace {port} with your local port, typically 3000)","variables":{"port":{"default":"3000","description":"Local development server port"}}}],"security":[],"paths":{"/requests":{"post":{"tags":["Requests"],"summary":"Create authentication request","description":"Creates a new authentication request that can be executed by the auth dapp.\n\n**Important:**\n- The `authChain` field is **required** and will be validated.\n- Signature validation is performed using `@dcl/crypto` Authenticator.\n- The `dcl_personal_sign` method is rejected, as is signing a Decentraland ephemeral message\n under any other method. Ordinary `personal_sign` / `eth_sign` requests are accepted.\n- The request will expire after the configured expiration time (default: 5 minutes).\n","operationId":"createRequest","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","description":"Wallet method to execute (e.g., 'eth_sendTransaction', 'personal_sign')"},"params":{"type":"array","items":{},"description":"Method parameters (any JSON-serializable type)"},"authChain":{"description":"Authentication chain of the wallet owner. **Required** — the signature is\nvalidated and the owner address is stored as the request `sender`.\n","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Auth link type (e.g., SIGNER, ECDSA_EPHEMERAL)"},"payload":{"type":"string","description":"Link payload"},"signature":{"type":"string","description":"Link signature"}},"required":["type","payload","signature"]},"minItems":1}},"required":["method","params","authChain"],"additionalProperties":false}}}},"responses":{"201":{"description":"Request created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid","description":"Unique request identifier"},"expiration":{"type":"string","format":"date-time","description":"Request expiration time (ISO 8601). Request must be consumed before this time."},"code":{"type":"number","minimum":0,"maximum":99,"description":"Random verification code (0-99) for visual confirmation on both client and auth dapp"}},"required":["requestId","expiration","code"]}}}},"400":{"description":"Invalid request (missing required fields, invalid authChain, signature validation failed)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}}}}}}}
```
## Poll for request outcome
> Polls for the outcome of an authentication request. \
> \
> This endpoint can be used as an alternative to WebSocket for receiving request outcomes.\
> The client should poll this endpoint periodically until a result is returned.\
> \
> \*\*Status Codes:\*\*\
> \- \`200\`: Request completed, outcome returned\
> \- \`204\`: Request not yet completed, continue polling\
> \- \`404\`: Request not found\
> \- \`410\`: Request expired
```json
{"openapi":"3.1.0","info":{"title":"Auth Server API","version":"1.0.0"},"tags":[{"name":"Requests","description":"Authentication request management endpoints"}],"servers":[{"url":"https://auth-api.decentraland.org","description":"Production server"},{"url":"https://auth-api.decentraland.zone","description":"Development server"},{"url":"http://localhost:{port}","description":"Local development server (replace {port} with your local port, typically 3000)","variables":{"port":{"default":"3000","description":"Local development server port"}}}],"security":[],"paths":{"/requests/{requestId}":{"get":{"tags":["Requests"],"summary":"Poll for request outcome","description":"Polls for the outcome of an authentication request. \n\nThis endpoint can be used as an alternative to WebSocket for receiving request outcomes.\nThe client should poll this endpoint periodically until a result is returned.\n\n**Status Codes:**\n- `200`: Request completed, outcome returned\n- `204`: Request not yet completed, continue polling\n- `404`: Request not found\n- `410`: Request expired\n","operationId":"pollRequest","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Request ID to poll for"}],"responses":{"200":{"description":"Request completed with outcome","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid","description":"Request identifier"},"sender":{"type":"string","description":"Address that executed the request"},"result":{"description":"Success result (any JSON-serializable type). Present when request succeeded."},"error":{"description":"Error details. Present when request failed.","type":"object","properties":{"code":{"type":"number","description":"Error code"},"message":{"type":"string","description":"Error message"},"data":{"description":"Additional error data (any type)"}},"required":["code","message"]}},"required":["requestId","sender"],"oneOf":[{"required":["result"]},{"required":["error"]}]}}}},"204":{"description":"Request not yet completed (continue polling)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"404":{"description":"Request not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"410":{"description":"Request expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}}}}}}}
```
## Submit request outcome
> Submits the outcome of a previously created request. If the request originated from a WebSocket client, the server will immediately emit the \`outcome\` event to that client and delete the request. Otherwise, the outcome is stored for later retrieval via polling.
```json
{"openapi":"3.1.0","info":{"title":"Auth Server API","version":"1.0.0"},"tags":[{"name":"Requests","description":"Authentication request management endpoints"}],"servers":[{"url":"https://auth-api.decentraland.org","description":"Production server"},{"url":"https://auth-api.decentraland.zone","description":"Development server"},{"url":"http://localhost:{port}","description":"Local development server (replace {port} with your local port, typically 3000)","variables":{"port":{"default":"3000","description":"Local development server port"}}}],"security":[],"paths":{"/v2/requests/{requestId}/outcome":{"post":{"tags":["Requests"],"summary":"Submit request outcome","description":"Submits the outcome of a previously created request. If the request originated from a WebSocket client, the server will immediately emit the `outcome` event to that client and delete the request. Otherwise, the outcome is stored for later retrieval via polling.\n","operationId":"submitOutcome","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Request ID to submit outcome for"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sender":{"type":"string","description":"Address that executed the request"},"result":{"description":"Success result (any JSON-serializable type). Required if error is not present."},"error":{"description":"Error details. Required if result is not present.","type":"object","properties":{"code":{"type":"number","description":"Error code"},"message":{"type":"string","description":"Error message"},"data":{"description":"Additional error data (any type)"}},"required":["code","message"]}},"required":["sender"],"oneOf":[{"required":["result"]},{"required":["error"]}]}}}},"responses":{"200":{"description":"Outcome accepted"},"400":{"description":"Bad request (invalid body or request already has a response)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"404":{"description":"Request not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"410":{"description":"Request expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}}}}}}}
```
## Get request validation status
> Returns whether a request requires additional validation.
```json
{"openapi":"3.1.0","info":{"title":"Auth Server API","version":"1.0.0"},"tags":[{"name":"Requests","description":"Authentication request management endpoints"}],"servers":[{"url":"https://auth-api.decentraland.org","description":"Production server"},{"url":"https://auth-api.decentraland.zone","description":"Development server"},{"url":"http://localhost:{port}","description":"Local development server (replace {port} with your local port, typically 3000)","variables":{"port":{"default":"3000","description":"Local development server port"}}}],"security":[],"paths":{"/v2/requests/{requestId}/validation":{"get":{"tags":["Requests"],"summary":"Get request validation status","description":"Returns whether a request requires additional validation.","operationId":"getRequestValidationStatus","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Request ID to check"}],"responses":{"200":{"description":"Validation status","content":{"application/json":{"schema":{"type":"object","properties":{"requiresValidation":{"type":"boolean","description":"Whether this request requires additional validation"}},"required":["requiresValidation"]}}}},"404":{"description":"Request not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"410":{"description":"Request expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}}}}}}}
```
## Notify request requires validation
> Notifies that the request requires additional user validation (e.g., visual code confirmation). \
> If the requester is connected via WebSocket, the server relays a \`request-validation-status\` event to that client.
```json
{"openapi":"3.1.0","info":{"title":"Auth Server API","version":"1.0.0"},"tags":[{"name":"Requests","description":"Authentication request management endpoints"}],"servers":[{"url":"https://auth-api.decentraland.org","description":"Production server"},{"url":"https://auth-api.decentraland.zone","description":"Development server"},{"url":"http://localhost:{port}","description":"Local development server (replace {port} with your local port, typically 3000)","variables":{"port":{"default":"3000","description":"Local development server port"}}}],"security":[],"paths":{"/v2/requests/{requestId}/validation":{"post":{"tags":["Requests"],"summary":"Notify request requires validation","description":"Notifies that the request requires additional user validation (e.g., visual code confirmation). \nIf the requester is connected via WebSocket, the server relays a `request-validation-status` event to that client.\n","operationId":"notifyRequestValidation","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Request ID to notify"}],"responses":{"204":{"description":"Notification accepted (no content)"},"404":{"description":"Request not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"410":{"description":"Request expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}}}}}}}
```
## Get request details
> Retrieves the details of an authentication request for execution.\
> \
> This endpoint is used by the auth dapp to recover request information before executing it.\
> The request must exist, not be expired, and pass IP address validation (if applicable).
```json
{"openapi":"3.1.0","info":{"title":"Auth Server API","version":"1.0.0"},"tags":[{"name":"Requests","description":"Authentication request management endpoints"}],"servers":[{"url":"https://auth-api.decentraland.org","description":"Production server"},{"url":"https://auth-api.decentraland.zone","description":"Development server"},{"url":"http://localhost:{port}","description":"Local development server (replace {port} with your local port, typically 3000)","variables":{"port":{"default":"3000","description":"Local development server port"}}}],"security":[],"paths":{"/v2/requests/{requestId}":{"get":{"tags":["Requests"],"summary":"Get request details","description":"Retrieves the details of an authentication request for execution.\n\nThis endpoint is used by the auth dapp to recover request information before executing it.\nThe request must exist, not be expired, and pass IP address validation (if applicable).\n","operationId":"getRequestDetails","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Request ID to retrieve"}],"responses":{"200":{"description":"Request details retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"expiration":{"type":"string","format":"date-time","description":"Request expiration time"},"code":{"type":"number","description":"Request verification code"},"method":{"type":"string","description":"Original method that was requested"},"params":{"type":"array","items":{},"description":"Original parameters for the method"},"sender":{"type":"string","description":"Sender address derived from auth chain (if applicable)"}},"required":["expiration","code","method","params"]}}}},"403":{"description":"IP validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"404":{"description":"Request not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"410":{"description":"Request expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.decentraland.org/apis/apis/auth-server/requests.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.