Skip to Content
Authentication

Authentication

All Gatelithix API requests require authentication via API keys passed as Bearer tokens.

API Key Types

Key TypePrefixUsage
Secret key (test)sk_test_Server-side sandbox requests
Secret key (live)sk_live_Server-side production requests
Publishable key (test)pk_test_Client-side tokenization (sandbox)
Publishable key (live)pk_live_Client-side tokenization (production)

Secret keys can perform all API operations. Never expose them in client-side code, browser JavaScript, or version control.

Publishable keys are restricted to tokenization operations. They are safe to use in browser-side hosted fields and mobile apps.

Environment Modes

Keys with _test_ in the prefix operate in sandbox mode. Test transactions are processed against simulated connectors and never charge real cards.

Keys with _live_ in the prefix operate in production mode. Live transactions are routed to real payment processors.

Bearer Token Usage

Pass your API key in the Authorization header as a Bearer token:

Authorization: Bearer sk_test_aBcDeFgHiJkLmNoPqRsTuVwX

Every API request without a valid Authorization header returns a 401 error with authentication_required code.

API Key Management

Create an API Key

The full plaintext key is returned only once in the creation response. Store it securely.

List API Keys

curl https://sandbox.api.gatelithix.com/v1/api-keys \
  -H "Authorization: Bearer sk_test_your_key_here"

Returns all keys for the merchant. The plaintext key is never included in list responses.

Rotate an API Key

curl -X POST https://sandbox.api.gatelithix.com/v1/api-keys/{keyID}/rotate \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Idempotency-Key: rot_$(uuidgen)"

Generates a new key value while preserving the key ID, name, and scopes. The old key is immediately invalidated.

Revoke an API Key

curl -X DELETE https://sandbox.api.gatelithix.com/v1/api-keys/{keyID} \
  -H "Authorization: Bearer sk_test_your_key_here"

Permanently deactivates the key. Revoked keys return invalid_api_key on any subsequent request.

Idempotency

All POST write endpoints require an Idempotency-Key header. This ensures that retrying a request (e.g., due to a network timeout) does not create duplicate operations.

Idempotency-Key: unique-request-id-here

Rules:

  • Same key with same parameters returns the cached response.
  • Same key with different parameters returns a 422 idempotency_param_mismatch error.
  • Concurrent requests with the same key return a 409 idempotency_conflict error.
  • Idempotency keys expire after 72 hours.

Use a UUID or other unique identifier for each distinct operation.

Getting StartedAuthorize