Requests

Authentication request management endpoints

Create authentication request

post

https://auth-api.decentraland.orghttps://auth-api.decentraland.zonehttp://localhost:3000

/requests

Creates a new authentication request that can be executed by the auth dapp.

Important:

• For methods other than dcl_personal_sign, the authChain field is required and will be validated.

• For dcl_personal_sign, the authChain field is optional.

• Signature validation is performed using @dcl/crypto Authenticator.

• The request will expire after the configured expiration time (default: 5 minutes).

Body

application/json

methodstringRequired

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

Example: personal_sign

Responses

201

Request created successfully

application/json

400

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

application/json

post

/requests

HTTPcURLJavaScriptPython

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": "..."
    }
  ]
}

Personal sign requestDCL personal sign request (no authChain required)

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

Poll for request outcome

get

https://auth-api.decentraland.orghttps://auth-api.decentraland.zonehttp://localhost:3000

/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}

HTTPcURLJavaScriptPython

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

https://auth-api.decentraland.orghttps://auth-api.decentraland.zonehttp://localhost:3000

/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

application/json

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

HTTPcURLJavaScriptPython

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..."
}

Successful outcomeFailed outcome

No content

Get request validation status

get

https://auth-api.decentraland.orghttps://auth-api.decentraland.zonehttp://localhost:3000

/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

HTTPcURLJavaScriptPython

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

{
  "requiresValidation": true
}

Notify request requires validation

post

https://auth-api.decentraland.orghttps://auth-api.decentraland.zonehttp://localhost:3000

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

404

Request not found

application/json

410

Request expired

application/json

post

/v2/requests/{requestId}/validation

HTTPcURLJavaScriptPython

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

No content

Get request details

get

https://auth-api.decentraland.orghttps://auth-api.decentraland.zonehttp://localhost:3000

/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}

HTTPcURLJavaScriptPython

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"
}