Build on the Crest standard

Quickstart

Key to first call in four steps

Code samples

Three minimal clients

Each hits the public Crest endpoint and handles the 404-indistinguishable invariant correctly — treat “not found” as “no public Crest”, never as “account doesn't exist”.

# curl
KEY="crst_xxxxxxxx.your_secret"
curl -sS \
  -H "Authorization: Bearer $KEY" \
  https://trustpadel.com/api/v1/players/sandbox-gold/rating
# 200 → { "handle": "sandbox-gold", "crest": { ... } }
# 404 → opaque; could be missing, minor, or private

Webhook signature verification

// node
import crypto from 'node:crypto'

export function verifyCrestWebhook(req, signingSecret) {
  const sig = req.headers['x-crest-signature']
  if (!sig) return false
  const [ts, hex] = sig.split(',')
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false  // ±5min
  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${ts}.${req.rawBody}`)
    .digest('hex')
  return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(hex, 'hex'))
}

Endpoints

The keyed surface

All keyed routes count toward your tier rate limit. Keyless /decoder routes don't. Deprecation + Sunset headers signal scheduled changes per RFC 8594 with a 6-month minimum window. Machine-readable spec (OpenAPI 3.1) available. Building an app that signs users in? Register an OAuth app for Sign in with TrustPadel.

Rate limits + tiers

Pick the volume you need

Tier upgrades route through billing — email developers@trustpadel.com with your prefix + intended use.

Scopes

Scope a key tightly

Keys carry a scope set. Write scopes (results:write, webhooks:manage) require Developer tier or above. A credential lost from a read-only integration can't mutate data.

Webhooks

At-least-once delivery, signed

Configure endpoints per key in /account/api-keys. Endpoints must be HTTPS. Delivery is at-least-once with exponential backoff. After repeated failures the endpoint pauses automatically; you resume it from the same page.

Signing

# Pseudocode
sig_header = req.headers['X-Crest-Signature']
ts, sig = sig_header.split(',')
if abs(now() - int(ts)) > 300: reject
expected = hmac_sha256(signing_secret, f"{ts}.{raw_body}")
if not const_time_eq(expected, sig): reject

Each request carries an X-Crest-Signature header containing an HMAC-SHA256 over <timestamp>.<raw-body> keyed by the signing secret returned at endpoint creation. Reject requests more than ±5 minutes from your clock to prevent replays. Always verify the signature before processing the payload.

Events

Sandbox players

Six fixtures covering the locked invariants

Hit these against your integration before pointing at production. The sandbox-minor and sandbox-private fixtures specifically verify the 404 invariant — your code must render the same UI for both as for a truly absent player.

Locked invariants

Non-negotiable across every endpoint, every tier, every release

If your integration depends on the inverse of any of these, please choose a different integration.