Requests

Authentication request management endpoints

Create authentication request

post

/requests

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

Body

methodstringRequired

Wallet method to execute (e.g., 'eth_sendTransaction', 'personal_sign')

Example: personal_sign

Responses

201

Request created successfully

application/json

requestIdstring · uuidRequired

Unique request identifier

expirationstring · date-timeRequired

Request expiration time (ISO 8601). Request must be consumed before this time.

codenumber · max: 99Required

Random verification code (0-99) for visual confirmation on both client and auth dapp

400

Invalid request (missing required fields, invalid authChain, signature validation failed)

application/json

post/requests

POST /requests HTTP/1.1
Host: auth-api.decentraland.org
Content-Type: application/json
Accept: */*
Content-Length: 263

{
  "method": "personal_sign",
  "params": [
    "Message to sign",
    "0x1234567890123456789012345678901234567890"
  ],
  "authChain": [
    {
      "type": "SIGNER",
      "payload": "0x1234567890123456789012345678901234567890",
      "signature": ""
    },
    {
      "type": "ECDSA_EPHEMERAL",
      "payload": "...",
      "signature": "..."
    }
  ]
}

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "expiration": "2024-01-01T12:10:00.000Z",
  "code": 42
}

Poll for request outcome

get

/requests/{requestId}

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

Path parameters

requestIdstring · uuidRequired

Request ID to poll for

Example: 550e8400-e29b-41d4-a716-446655440000

Responses

200

Request completed with outcome

application/json

anyOptional

or

anyOptional

204

Request not yet completed (continue polling)

application/json

404

Request not found

application/json

410

Request expired

application/json

get/requests/{requestId}

GET /requests/{requestId} HTTP/1.1
Host: auth-api.decentraland.org
Accept: */*

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "sender": "0x1234567890123456789012345678901234567890",
  "result": "0xabcdef1234567890..."
}

Submit request outcome

post

/v2/requests/{requestId}/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.

Path parameters

requestIdstring · uuidRequired

Request ID to submit outcome for

Body

anyOptional

or

anyOptional

Responses

200

Outcome accepted

No content

400

Bad request (invalid body or request already has a response)

application/json

404

Request not found

application/json

410

Request expired

application/json

post/v2/requests/{requestId}/outcome

POST /v2/requests/{requestId}/outcome HTTP/1.1
Host: auth-api.decentraland.org
Content-Type: application/json
Accept: */*
Content-Length: 88

{
  "sender": "0x1234567890123456789012345678901234567890",
  "result": "0xabcdef1234567890..."
}

No content

Get request validation status

get

/v2/requests/{requestId}/validation

Returns whether a request requires additional validation.

Path parameters

requestIdstring · uuidRequired

Request ID to check

Responses

200

Validation status

application/json

requiresValidationbooleanRequired

Whether this request requires additional validation

404

Request not found

application/json

410

Request expired

application/json

get/v2/requests/{requestId}/validation

GET /v2/requests/{requestId}/validation HTTP/1.1
Host: auth-api.decentraland.org
Accept: */*

{
  "requiresValidation": true
}

Notify request requires validation

post

/v2/requests/{requestId}/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.

Path parameters

requestIdstring · uuidRequired

Request ID to notify

Responses

204

Notification accepted (no content)

No content

404

Request not found

application/json

410

Request expired

application/json

post/v2/requests/{requestId}/validation

POST /v2/requests/{requestId}/validation HTTP/1.1
Host: auth-api.decentraland.org
Accept: */*

No content

Get request details

get

/v2/requests/{requestId}

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

Path parameters

requestIdstring · uuidRequired

Request ID to retrieve

Example: 550e8400-e29b-41d4-a716-446655440000

Responses

200

Request details retrieved successfully

application/json

expirationstring · date-timeRequired

Request expiration time

codenumberRequired

Request verification code

methodstringRequired

Original method that was requested

senderstringOptional

Sender address derived from auth chain (if applicable)

Example: 0x1234567890123456789012345678901234567890

403

IP validation failed

application/json

404

Request not found

application/json

410

Request expired

application/json

get/v2/requests/{requestId}

GET /v2/requests/{requestId} HTTP/1.1
Host: auth-api.decentraland.org
Accept: */*

{
  "expiration": "2024-01-01T12:10:00.000Z",
  "code": 42,
  "method": "personal_sign",
  "params": [
    "Message to sign",
    "0x1234567890123456789012345678901234567890"
  ],
  "sender": "0x1234567890123456789012345678901234567890"
}