HTTP API

API information & reference

How to integrate with the public HTTP API: environments, auth headers, optional HMAC signing, runnable examples, and common failure modes. Domains below are illustrative—replace with your deployment.

Overview

The API speaks HTTPS + JSON: unless noted, request and response bodies are UTF-8 JSON; prefer Accept: application/json.

Examples demonstrate fields and flows only. Use console-issued secrets in production and never commit private keys or webhook secrets to source control.

Environments & base URL

Production: illustrative base is https://api.example.com with a /v1 version prefix on paths.

Staging / sandbox: use a separate host and credentials to avoid mixing data; switch environment in the console and copy the matching Base URL.

Authentication

Send Authorization: Bearer followed by your access token string for user or service tokens issued by the console.

Some machine-to-machine flows may allow an API key (e.g. X-Api-Key) when enabled—never ship long-lived secrets to browser clients.

Pass X-Request-Id (UUID) on mutating calls to simplify tracing across services.

Request signing (optional)

When signing is enabled, include X-Timestamp (Unix seconds), X-Nonce, and X-Signature alongside auth headers.

Build a canonical string from METHOD, PATH (including query), TIMESTAMP, NONCE, and the lowercase hex SHA256 of the raw body bytes (use the hash of an empty string for empty bodies).

Compute HMAC-SHA256 with your Signing Secret over UTF-8 bytes of the canonical string; emit lowercase hex as X-Signature. The server recomputes and compares to reject tampering and replays.

Canonical string (pseudocode)

canonical = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + SHA256(UTF8(BODY_OR_EMPTY))
signature = HMAC_SHA256(secret, UTF8(canonical)) // hex 小写输出

Calling with cURL

Minimal read-only request—swap the host and token to validate connectivity and auth from your terminal.

curl -X GET 'https://api.example.com/v1/me' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'X-Request-Id: 550e8400-e29b-41d4-a716-446655440000'

Calling from JavaScript / Node

Use fetch in browsers or Node 18+. Keep secrets in environment variables or a secret manager on the server; do not embed them in client bundles.

const res = await fetch('https://api.example.com/v1/me', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Request-Id': crypto.randomUUID(),
  },
})
if (!res.ok) throw new Error(`HTTP ${res.status}`)
const data = await res.json()

Errors & troubleshooting

401 Unauthorized: missing, expired, or invalid token—refresh credentials or re-run the OAuth / API-key flow.

403 Forbidden: insufficient scopes or failed signature—verify algorithm, clock skew, and that keys belong to the same environment.

429 Too Many Requests: rate limited—honor Retry-After and apply exponential backoff.

5xx: transient or server-side failure—retry with backoff and include X-Request-Id when contacting support.

Rate limits

Limits are applied per sliding window (e.g. by app + IP or app + subject). Responses include X-RateLimit-Remaining and X-RateLimit-Reset when applicable.

Prefer async jobs or higher quotas for bulk work; smooth bursts with queues and backoff.

Webhook signature verification

Events are delivered as HTTP POST with JSON bodies. Headers include X-Webhook-Timestamp and X-Webhook-Signature.

Concatenate timestamp, a single dot, and the raw body bytes; compute HMAC-SHA256 with your Webhook Secret and compare to the header (enforce a short clock skew window to mitigate replays).

Return 2xx quickly after verification; retries use exponential backoff—design handlers to be idempotent.