API Authentication

The Ohio Sales Tax Rate API employs industry-standard Bearer token authentication over TLS 1.3. Every request to protected endpoints (/api/v1/rates, /api/v1/counties, /api/v1/webhooks) must supply a valid organization API key.

Authorization Header

Provide your secret API key in the Authorization HTTP header with the Bearer scheme:

GET /api/v1/rates?county=franklin HTTP/1.1
Host: app.ohiosalestaxcalculator.com
Authorization: Bearer ostx_live_9f8e7d6c5b4a3210e4d3c2b1...
Accept: application/json

Token Types & Prefixes

All keys generated via the Platform Dashboard feature explicit prefixes to prevent accidental sandbox/production cross-talk:

Prefix	Environment	Purpose
`ostx_live_`	Production	Live transactions, production ERP checkouts, and official audit filings.
`ostx_test_`	Sandbox	Staging environments, local development, and CI/CD test pipelines.

Security Architecture

Cryptographic SHA-256 One-Way Hashing

We practice zero-knowledge key storage. When an API key is generated:

A cryptographically random 256-bit token is minted client-side.
The raw key is hashed using SHA-256.
Only the SHA-256 hash and a 16-character public prefix (e.g., ostx_live_9f8e7d) are stored in our encrypted database.
The plaintext key is displayed exactly once in the dashboard and is never stored or logged.

Instant Key Revocation

If an API key is accidentally committed to public version control or exposed:

Open API Keys & Webhooks.
Locate the compromised key prefix and click Revoke Key.
The key is instantly invalidated across all edge nodes immediately, rejecting subsequent requests with 401 Unauthorized.

Zero-Downtime Key Rotation

To rotate keys without service interruption:

Generate a new secondary key in your dashboard.
Deploy the new key to your staging/production environments.
Verify traffic on the new key prefix in the telemetry table.
Revoke the old primary key.

Code Examples

Node.js / Fetch

const response = await fetch("https://app.ohiosalestaxcalculator.com/api/v1/rates?county=warren", {
  headers: {
    "Authorization": `Bearer ${process.env.OHIO_SALES_TAX_API_KEY}`,
    "Accept": "application/json"
  }
});

Python / Requests

import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['OHIO_SALES_TAX_API_KEY']}",
    "Accept": "application/json"
}
response = requests.get(
    "https://app.ohiosalestaxcalculator.com/api/v1/rates?county=warren",
    headers=headers
)

cURL

curl -X GET "https://app.ohiosalestaxcalculator.com/api/v1/rates?county=warren" \
  -H "Authorization: Bearer ostx_live_YOUR_KEY"

Authentication Error Handling

When authentication fails, our API returns standard RFC 7807 Problem Details:

1. Missing Authorization Header (`401 Unauthorized`)

{
  "type": "https://ohiosalestaxcalculator.com/errors/unauthorized",
  "title": "API Key Required",
  "status": 401,
  "detail": "An Authorization header with Bearer ostx_... token is required.",
  "request_id": "req_auth_missing_1a2b"
}

2. Invalid or Revoked API Key (`401 Unauthorized`)

{
  "type": "https://ohiosalestaxcalculator.com/errors/invalid-api-key",
  "title": "Invalid or Revoked API Key",
  "status": 401,
  "detail": "The provided API key is invalid, revoked, or belongs to a suspended organization.",
  "request_id": "req_auth_revoked_3c4d"
}