Skip to main content

Authentication

Peak Gateway uses several credentials at distinct trust boundaries. Do not substitute one credential type for another.

OAuth 2.0 client credentials

Server-to-server integrations authenticate with an OAuth client ID and secret, then use the returned short-lived access token. Client authentication may use HTTP Basic or the OAuth client_secret_post form parameters, and either form must include the exact machine-request marker; this positive marker is required even when the request has no browser metadata:

curl -sS -X POST "https://api.peakgateway.co/auth/oauth2/token" \
  -u "${PEAK_CLIENT_ID}:${PEAK_CLIENT_SECRET}" \
  -H "X-Gateway-OAuth-Machine-Request: 1" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=hosted-payments:write"

The same X-Gateway-OAuth-Machine-Request: 1 header is required on direct client-auth requests to /oauth2/introspect and /oauth2/revoke, whether credentials use Basic or client_id/client_secret form parameters. The /oauth2/token-exchange endpoint accepts Basic client authentication and requires the same marker. Send exactly one marker header with the value 1; requests missing it or carrying duplicate, blank, or other values are rejected. Do not send both client-auth forms in one request.

Send the token on API requests:

Authorization: Bearer <ACCESS_TOKEN>

The token's scopes must cover the operation. Request only scopes assigned to the client; the token endpoint does not grant scopes the client does not own.

API-key exchange

A Gateway API key is a long-lived credential used only to obtain a short-lived OAuth access token:

curl -sS -X POST "https://api.peakgateway.co/auth/oauth2/api-key/token" \
  -H "X-Api-Key: ${PEAK_API_KEY}"

Do not send the raw API key to ordinary resource endpoints.

Checkout session tokens

Shopper-facing payment requests use the token associated with a checkout session. A session token authorizes only that checkout flow. It is not an OAuth client credential and does not grant management access.

Portal and internal identities

  • The merchant and admin portals use Firebase-backed user authentication plus organization, location, and role authorization.
  • Private service-to-service endpoints use Google Cloud Run IAM identity.

These boundaries are not public API authentication alternatives. Public integrations should use OAuth access tokens, SDK-managed OAuth, or checkout session tokens as documented for the operation.

Token handling

  • Keep OAuth client secrets and API keys in a server-side secret manager.
  • Cache access tokens only until their reported expiration and refresh before use when necessary.
  • Never log credentials, bearer tokens, session tokens, or full payment data.
  • Provision separate credentials for staging and production.
  • Rotate or revoke a compromised client or API key immediately.
  • Treat 401 as missing, expired, or invalid authentication; treat 403 as an authenticated caller that lacks the required scope or resource authority.