Quick Start - 10 Minute Integration Guide

This guide is for third-party integrators to complete API authentication in 10 minutes. No theory, just the shortest path to success.

Prerequisites (30 seconds)

After creating your Namespace, you will receive:

• uuid (unique identifier)
• api_key (shown only once - save it immediately!)
• Contact our team to obtain your API credentials and base URL

📝

How to Get API Access:

Email [email protected] with:

• Company name and use case
• Expected transaction volume
• Integration timeline

You'll receive your credentials within 24 hours including:

• UUID - Namespace identifier
• API_KEY - Authentication secret (save immediately!)
• BASE_URL - Your API endpoin

Step 1: Password-Based Login (1 minute)

Endpoint

POST /system/login

Request Body

{
  "name": "<uuid>",
  "password": "<api_key>"
}

Response

{
  "auth_token": "<temp_token>"
}

⚠️

This token is only for certificate application.

Step 2: Request Client Certificate (2 minutes)

Endpoint

POST /system/service/auth_cert

Request Headers

X-Molly-Wallet-Token: <temp_token>

Request Body

{
  "common_name": "<uuid>",
  "alt_names": "namespace.srv"
}

Response (Save This!)

{
  "ca": "-----BEGIN CERTIFICATE-----...",
  "client_cert": "-----BEGIN CERTIFICATE-----...",
  "client_key": "-----BEGIN PRIVATE KEY-----..."
}

✅

Password authentication phase complete.

Step 3: Certificate-Based Login (2 minutes)

From this point forward, do not use api_key.

Endpoint

POST /system/login

Request Body

{
  "name": "<uuid>",
  "password": ""
}

HTTPS Requirements (Critical!)

• Use client_cert + client_key
• Trust the ca certificate
• TLS SNI must be set to: loulilouwai.net

Response

{
  "auth_token": "<final_token>"
}

🎉

This is your production business token.

Step 4: Calling Business APIs (3 minutes)

Every Request Must:

1. Use HTTPS with client certificate
2. Include token header:

   X-Molly-Wallet-Token: <final_token>

❌ Not Supported: Authorization: Bearer xxx

Handling 403 Errors (30 seconds)

If You Receive HTTP 403 Forbidden:

1. Re-execute Step 3 (certificate login)
2. Obtain a new token
3. Retry the request

⚠️

No need to request a new certificate.

Top 5 Common Mistakes

1. ❌ Using Bearer Token (system doesn't recognize it)
2. ❌ Forgetting to set SNI = loulilouwai.net
3. ❌ Re-running password flow after 403 error
4. ❌ Losing api_key (can only rebuild namespace)
5. ❌ Sending token without certificate

What You've Accomplished

✅ Long-term client certificate obtained
✅ Refreshable business token acquired
✅ Authorized to call all APIs securely

Next Steps (Optional)

• Code Examples - Curl, Go, Java, Node.js, Python
• Troubleshooting - Common issues and solutions
• Advanced Topics - Token refresh, certificate rotation