Authentication in Walta V2

All API requests to Walta V2 must be made over HTTPS.
Authentication is enforced at two levels:

1. Domain Validation – every request first verifies that the {domain} in the path is a registered merchant domain.
2. Role-Specific Auth – once the domain is valid, additional checks apply depending on whether the caller is an agent or a merchant.

1. Domain-Level Validation

Every Walta endpoint begins with a domain prefix: https://api.waltacheckout.com/{domain}/...

Before any other logic executes, Walta runs a global middleware to ensure the domain exists in the merchants table.

# checkout/middleware.py
await self.validate_domain(domain_name)

If the domain is invalid, the request fails with:

{ "error": "Domain '{domain}' not found", "status_code": 404 }

2. Agent Authentication

Agents interact with agent-prefixed routes:

/{domain}/agent/session/create
/{domain}/agent/cart/add
/{domain}/agent/checkout/pay

Session Creation

Agents must first create a session using their user key (provided during onboarding). This request issues a short-lived session_key used for subsequent agent calls.

curl -X POST https://api.waltacheckout.com/{domain}/agent/session/create \
  -H "X-User-Key: {user_key}" \
  -d '{}'

Example response:

{ "session_key": "sess_abc123xyz" }

Using the Session Key

Once created, the session_key is required for all agent actions (cart, browse, checkout). Send it in the Authorization header:

curl https://api.waltacheckout.com/{domain}/agent/cart/view \
  -H "Authorization: Bearer {session_key}"

Agent Security Features

• Short-lived session tokens (auto-expire to prevent misuse)
• All actions are logged and scoped to the agent identity
• Keys should never be exposed in client-side code

3. Merchant Authentication

Merchants interact with merchant-prefixed routes:

/{domain}/merchant/product/add
/{domain}/merchant/product/list
/{domain}/merchant/product/edit/{product_id}

API Key Authentication

Merchants must include their API key (issued at onboarding) in the x-api-key header for every request.

curl -X POST https://api.waltacheckout.com/{domain}/merchant/product/add \
  -H "x-api-key: {merchant_api_key}" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Sample Product", "cost": 10.0 }'

The middleware (merchant/middleware.py) verifies that this key exists and matches the {domain}. Invalid or missing keys return:

{ "error": "Invalid API key", "status_code": 403 }

4. Security Principles

• Scoped Access: Agent tokens only allow agent actions; merchant keys only allow merchant actions.
• Store Isolation: All product and order changes are bound to the validated store_id.
• Encryption: Sensitive data (e.g., shipping addresses) is encrypted at rest and in transit.
• Logging: Every request is logged for monitoring and auditing.

5. Example Flow

Agent Checkout Flow

• Agent calls /agent/session/create → receives a session_key.
• Uses session_key to browse products and add to cart.
• Calls /checkout/pay with payment token (via Stripe) to complete purchase.

Merchant Product Management Flow

• Merchant sends requests with x-api-key header.
• Merchant endpoints allow CRUD on product listings (scoped to domain).
• Unauthorized or invalid keys are immediately rejected.

Using SDKs

When using an official Walta SDK, domain validation and token handling are abstracted away.
Simply configure the SDK with your {domain} and credentials, and it will handle authentication internally.