Authentication & API Keys

All interactions with the TaxWisp Platform Independent Integration API require secure authentication using your TaxWisp API Key.

---

Obtaining Your API Key

1. Log in to your TaxWisp Merchant Dashboard.
2. Navigate to Settings → API Credentials.
3. Copy your API Key (Client Secret).
4. Store the key in your secure server environment variables (e.g., .env, AWS Secrets Manager, or Doppler).

Critical Security Rule

Your TaxWisp API Key provides administrative access to initiate customer sessions and fetch exemption records.

• NEVER expose this key in client-side code (React, Vue, HTML, mobile apps, or browser JavaScript).
• NEVER commit API keys to public or private source code repositories.
• All requests using X-TaxWisp-Api-Key MUST originate from your backend server.

---

Authentication Header

Authenticate your HTTP requests to TaxWisp by passing your API key in the X-TaxWisp-Api-Key header:

X-TaxWisp-Api-Key: YOUR_TAXWISP_API_KEY
Content-Type: application/json

---

Server Implementation Examples

Below are standard backend implementations for making authenticated requests to TaxWisp.

Node.js (Fetch / Axios)

// Example using native Node.js fetch (v18+)
const TAXWISP_API_URL = "https://taxwisp.ai/api/v1/external";
const TAXWISP_API_KEY = process.env.TAXWISP_API_KEY;

async function createCustomerSession(customerId, customerEmail) {
  const response = await fetch(`${TAXWISP_API_URL}/customer-sessions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-TaxWisp-Api-Key": TAXWISP_API_KEY,
    },
    body: JSON.stringify({
      customerId,
      customerEmail,
    }),
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`TaxWisp API error (${response.status}): ${errorBody}`);
  }

  return await response.json();
}

Python (Requests)

import os
import requests

TAXWISP_API_URL = "https://taxwisp.ai/api/v1/external"
TAXWISP_API_KEY = os.environ.get("TAXWISP_API_KEY")

def create_customer_session(customer_id: str, customer_email: str) -> dict:
    url = f"{TAXWISP_API_URL}/customer-sessions"
    headers = {
        "Content-Type": "application/json",
        "X-TaxWisp-Api-Key": TAXWISP_API_KEY
    }
    payload = {
        "customerId": customer_id,
        "customerEmail": customer_email
    }

    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
    return response.json()

PHP (cURL)

<?php

function createCustomerSession($customerId, $customerEmail) {
    $apiKey = getenv('TAXWISP_API_KEY');
    $url = 'https://taxwisp.ai/api/v1/external/customer-sessions';

    $payload = json_encode([
        'customerId' => $customerId,
        'customerEmail' => $customerEmail
    ]);

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-TaxWisp-Api-Key: ' . $apiKey
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("TaxWisp API request failed with status: " . $httpCode);
    }

    return json_decode($response, true);
}

---

HTTP Status Codes & Error Handling

TaxWisp APIs use standard HTTP response codes to report the success or failure of requests:

Status Code	Meaning	Resolution
200 OK	The request succeeded.	Process response data normally.
400 Bad Request	Missing or invalid parameters in request body or query string.	Verify customerId, customerEmail, or pagination parameters.
401 Unauthorized	Invalid, expired, or missing X-TaxWisp-Api-Key header.	Verify that the API Key in your environment variable matches your dashboard settings.
403 Forbidden	The provided key lacks permission to access the requested resource.	Confirm your account is active and verified in TaxWisp.
429 Too Many Requests	Rate limit exceeded.	Implement exponential backoff retry logic.
500 Internal Error	TaxWisp internal service error.	Retry after a brief delay or check TaxWisp Support.

---

Best Practices

1. Rotate Keys Responsibly: If an API key is accidentally exposed, immediately generate a new key in the TaxWisp dashboard and update your production environment.
2. Environment Separation: Use separate API keys for your staging and production environments to prevent cross-environment data contamination.
3. Use HTTPS Exclusively: All API requests must be transmitted over TLS/HTTPS. Plain HTTP requests are rejected.