Switch Merchant

August 3, 2026 ยท View on GitHub

Use case

Switches the dashboard operator to a different merchant workspace and returns updated session context.

Authentication

Dashboard protected. Send Authorization: Bearer <jwt_token>. In sandbox, also send x-feature: decision-engine.

For local development, start with:

export BASE_URL=http://localhost:8080
export AUTH_HEADER="Authorization: Bearer <jwt_token>"
# Sandbox only:
# export BASE_URL=https://sandbox.hyperswitch.io
# export FEATURE_HEADER="x-feature: decision-engine"

Request

  • Method and path: POST /auth/switch-merchant
  • Parameters: none.
  • Body: JSON body with merchant_id from /auth/merchants.

Example

Switch merchant

curl --location "$BASE_URL/auth/switch-merchant" \
  --header "$AUTH_HEADER" \
  --header "Content-Type: application/json" \
  --data '{
  "merchant_id": "merchant_demo"
}'

Response

{
  "token": "eyJ...",
  "user_id": "user_123",
  "email": "operator@example.com",
  "merchant_id": "merchant_demo",
  "role": "admin",
  "merchants": [
    { "merchant_id": "merchant_demo", "merchant_name": "Demo Merchant", "role": "admin" }
  ]
}

Notes

  • Refresh stored dashboard auth context with the returned token/session data.
  • Use this before reading merchant-scoped analytics.