Skip to main content

Auth Proxy API Reference

Complete API documentation for the Duo Auth Proxy endpoints and message formats.

Authentication​

All WebSocket connections require authentication via Firebase ID tokens included in the first message.

Token Format​

<JSON_MESSAGE>, <FIREBASE_ID_TOKEN>

Example:

{
  "setup_msg": "base64_encoded_operation_data",
}, <firebase_id_token>

WebSocket Endpoints​

Message Flows​

1. Keygen (DKG)​

Purpose: Create a new MPC wallet for the authenticated user.

First Message (Authentication + DKG Request):

{
  "setup_msg": "base64_encoded_dkg_data",
}, <firebase_id_token>

Flow:

  1. Client sends authenticated DKG request
  2. Auth Proxy verifies Firebase token and creates/retrieves user
  3. Auth Proxy establishes connection to Duo Server
  4. MPC DKG protocol executes through bidirectional message relay
  5. On completion, Duo Server returns key_id to auth-proxy, and auth-proxy creates a new Wallet for the user. This message is NOT relayed to the client.
  6. Auth Proxy creates wallet mapping: User → Wallet(key_id)

Sequence Diagram:

2. Post Keygen Flows​

Once the keygen is done, the Wallet is already existing in the auth-proxy. Signgen and Refresh protocols follow this flow:

First Message (Authentication + Protocol Request Metadata):

{
  "setup_msg": "base64_encoded_dsg_data",
}, <firebase_id_token>

Access Control:

  • In post keygen flows, the key_id is extracted from the setup_msg.
  • Auth Proxy verifies the authenticated user owns the wallet with the specified key_id
  • Request is rejected if user doesn't own the wallet

Flow:

  1. Client sends authenticated DSG request with key_id
  2. Auth Proxy verifies Firebase token and user ownership of wallet
  3. If authorized, establishes connection to Duo Server
  4. MPC DSG protocol executes through bidirectional message relay

HTTP Endpoints​

GET /v3/verifying-key​

Purpose: Retrieve the verifying key for the Duo Server.

Authentication: None required (public endpoint)

Request:

GET /v3/verifying-key HTTP/1.1
Host: your-auth-proxy:9090

Response:

{
  "verifying_key": "base64_encoded_public_key"
}

Usage: Called by SDK to get the public key of the Duo Server.

Data Models​

User​

{
  "uuid": "firebase_user_uuid",
  "created_at": "2024-01-15T10:30:00Z"
}

Wallet​

{
  "key_id": "mpc_wallet_key_identifier",
  "user_uuid": "firebase_user_uuid",
  "created_at": "2024-01-15T10:35:00Z"
}

Client Integration Examples​

JavaScript/React Native​

TODO: add react native client code / link

Rate Limiting​

The Auth Proxy can be configured with Nginx or similar to limit the number of requests per user/IP to prevent abuse.

Security Considerations​

  1. Use HTTPS/WSS in production - auth-proxy must be run behind a secure reverse proxy
    • Use Nginx or similar to handle SSL termination