Authentication

API Key Authentication

Include these headers on every request:

curl https://api.aptcommerce.com/v1/transactions \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Key Types

Publishable vs Secret Keys

Idempotency

Include an Idempotency-Key header on POST requests to safely retry without creating duplicates.

curl -X POST https://api.aptcommerce.com/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{"amount": 5000, "currency": "usd", "payment_method": "card"}'

Idempotency keys expire after 24 hours. Use a UUID or other unique identifier per request.

Transport security (TLS)

APT requires TLS 1.2 as the minimum and negotiates TLS 1.3 by default. TLS 1.1 and below are rejected at the edge. The cipher policy is AEAD-only (AES-GCM, ChaCha20-Poly1305) with ECDHE key exchange. HSTS is enforced on all hostnames.

# Force a TLS floor and observe the negotiated version
curl -v --tlsv1.2 --tls-max 1.3 https://api.aptcommerce.com/v1/health

# Node — enforce TLS 1.2 floor on outbound clients
const agent = new https.Agent({ minVersion: 'TLSv1.2' });

See Transport & Message Security for the supported-protocol matrix, build/CI guidance, deprecation timelines, and how to subscribe to the tls.cipher_policy.changed webhook.

Certificate management

APT edge certificates are issued by public CAs and rotate automatically every 60–90 days. Do not pin the leaf certificate. If your compliance program requires pinning, pin the SPKI of the issuing CA and subscribe to the certificate.rotated webhook. Active fingerprints are published at /v1/trust/fingerprints and the rotation calendar at https://trust.aptcommerce.com/calendar.ics.

Message-level encryption (MLE)

For endpoints that carry sensitive payloads (PAN, full bank account, full Tax ID, custody keys), APT supports wrapping the entire request and response body in a JWE envelope (RFC 7516) on top of TLS. MLE is optional today and will become required for new sensitive-data endpoints in a future release with at least 12 months' notice.

# Fetch the current MLE public key for your merchant
GET /v1/mle/keys/current

# Then send the JWE-wrapped body
POST /v1/transactions
Authorization: Bearer sk_live_...
Content-Type: application/jose
X-APT-MLE: v1
X-APT-MLE-Response: required

eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoibWxlX2tleV8wMUhXIn0...

Full quickstart, key rotation behavior, and error codes (mle_required, mle_kid_unknown, mle_decrypt_failed) in Transport & Message Security.

Error Responses

Authentication errors return a standard JSON error body:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid.",
    "status": 401
  }
}

Key Management

Manage your API keys in the API Keys settings. You can roll keys at any time — the old key remains active for 24 hours to allow migration.