Skip to content

Authentication & Environments

This page covers how to authenticate with the CX Platform and which environments are available for testing and production use.

Authentication

The CX Platform uses API Key authentication. Every request must include a valid API key in the CX-API-KEY HTTP header.

API Key Header

Include the CX-API-KEY header in every request:

POST /cx/v2/action/setCustomer HTTP/1.1
Host: cx2-main.pit.cxgp.us
CX-API-KEY: YOUR_API_KEY
Content-Type: application/json

Key Hierarchy

API keys are issued at two levels, each with a different access scope:

Key Level Access Scope Use Case
Implementation All locations within a single implementation Implementation-level integrations, multi-location management
Location A single service location only Location-specific POS systems, kiosks, single-site apps

Note

Keys only operate at the level they are issued. An Implementation key cannot be used to access a Location-scoped endpoint, and a Location key cannot be used to access other locations or implementation-level endpoints. If configuration is set at the Implementation level, the Location key inherits that configuration. If configuration is set at the Location level, it overrides any Implementation-level configuration.

Partner Onboarding Flow

For partner-led onboarding, the implementation-backed flow is:

  1. Assumption — CX Support shares an Implementation API key with the partner.
  2. Generate a Location API key — Call POST /cx/v2/apikey with the Implementation API key.
  3. Create the Service Location — Call POST /cx/v2/action/setServiceLocation with the generated Location API key.
  4. Call Location-Scoped APIs for that Service Location — Use the same Location API key for downstream operations such as POST /cx/v2/action/setCustomer, payment requests, statements, scheduling, and other location-scoped endpoints.

This flow is reflected in the current Java SDK integration as below:

  • ApiKeyApi.createApiKeyForNewLocation() creates the location-scoped API key.
  • ServiceLocationApi.setServiceLocation(...) creates or updates the service location tied to that key.
  • CustomersApi.setCustomer(...) is one example of a location-scoped operation available after service-location setup.

Provisioning Example

# Step 1: Assumption
# CX Support has shared an Implementation API key with your team.

# Step 2: Generate a Location API key using the Implementation API key
curl -X POST "https://cx2-main.pit.cxgp.us/cx/v2/apikey" \
  -H "CX-API-KEY: ${IMPLEMENTATION_API_KEY}"

# Example response
# {"apiKey":"LOCATION_API_KEY"}

# Step 3: Create the Service Location using the generated Location API key
curl -X POST "https://cx2-main.pit.cxgp.us/cx/v2/action/setServiceLocation" \
  -H "CX-API-KEY: ${LOCATION_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PetHealth Inc",
    "locale": "en-US",
    "primaryWebsite": "https://www.globalpayments.com",
    "timeZone": "America/Denver",
    "primaryPhone": {
      "value": "+18015555555"
    },
    "primaryEmail": {
      "value": "pethealth@globalpay.com"
    },
    "primaryAddress": {
      "country": "US",
      "streetAddress1": "123 Easy Street",
      "streetAddress2": "Suite 101",
      "streetAddress3": "Testington, Alabama",
      "postalCode": "55555",
      "poBox": "PO Box 12345"
    }
  }'

# Step 4: Example downstream location-scoped call using the same Location API key
# This example creates a customer. After service-location setup, you can also
# call other location-scoped endpoints with the same key.
curl -X POST "https://cx2-main.pit.cxgp.us/cx/v2/action/setCustomer" \
  -H "CX-API-KEY: ${LOCATION_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "givenName": "Ol",
    "familyName": "Persson",
    "displayCustomerId": "Customer-12345",
    "primaryPhone": {
      "value": "+18015555555"
    },
    "primaryEmail": {
      "value": "cx-test@tsys.com"
    }
  }'

import com.gp.cx.sdk.api.ApiKeyApi;
import com.gp.cx.sdk.api.CustomersApi;
import com.gp.cx.sdk.api.ServiceLocationApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.model.ChannelEmailDTO;
import com.gp.cx.sdk.model.ChannelPhoneDTO;
import com.gp.cx.sdk.model.ServiceLocationDTO;
import com.gp.cx.sdk.model.ApiKeyResponseDTO;
import com.gp.cx.sdk.model.CustomerDTO;

// Step 1: Assumption
// CX Support has shared an Implementation API key with your team.

// Step 2: Generate a Location API key using the Implementation API key
CxSdkClient implementationClient = new CxSdkClient.Builder()
    .apiKey(System.getenv("CX_IMPLEMENTATION_API_KEY"))
    .baseUrl("https://cx2-main.pit.cxgp.us")
    .build();

ApiKeyApi apiKeyApi = implementationClient.getApiKeyApi();
ApiKeyResponseDTO keyResponse = apiKeyApi.createApiKeyForNewLocation();
String locationApiKey = keyResponse.getApiKey();

// Step 3: Create the Service Location using the generated Location API key
CxSdkClient locationClient = new CxSdkClient.Builder()
    .apiKey(locationApiKey)
    .baseUrl("https://cx2-main.pit.cxgp.us")
    .build();

ServiceLocationApi serviceLocationApi = locationClient.getServiceLocationApi();
ServiceLocationDTO serviceLocation = new ServiceLocationDTO()
    .name("PetHealth Inc")
    .locale("en-US")
    .primaryWebsite("https://www.globalpayments.com")
    .timeZone("America/Denver")
    .primaryPhone(new ChannelPhoneDTO().value("+18015555555"))
    .primaryEmail(new ChannelEmailDTO().value("pethealth@globalpay.com"));

ServiceLocationDTO createdLocation = serviceLocationApi.setServiceLocation(serviceLocation);

// Step 4: Example downstream location-scoped call using the same Location API key
// This example creates a customer. After service-location setup, you can also
// call other location-scoped APIs with the same key.
CustomersApi customersApi = locationClient.getCustomersApi();
CustomerDTO customer = new CustomerDTO()
    .givenName("Ol")
    .familyName("Persson")
    .displayCustomerId("Customer-12345")
    .primaryPhone(new ChannelPhoneDTO().value("+18015555555"))
    .primaryEmail(new ChannelEmailDTO().value("cx-test@tsys.com"));

CustomerDTO response = customersApi.setCustomer(customer);

REST vs SDK versioning

REST API examples on this site use explicit versioned paths such as /cx/v2/.... Java SDK clients should continue to use the environment host only in baseUrl(...) and should not append /cx/v2.

Note

Customer creation is scoped by the Location API key used for authentication. You do not need to send a separate service-location reference in the setCustomer request when you are already calling with the location-scoped key.

Key Management

API keys are provisioned through the CX Platform:

  • Implementation keys can generate Location-level keys within their scope
  • Key rotation and revocation requests are handled by the CX Platform support team

Security Best Practices

Protect Your API Keys

API keys grant access to your CX Platform data. Treat them like passwords.

  • Never commit keys to source control — Use .gitignore to exclude configuration files containing keys.
  • Use environment variables — Store keys in environment variables or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault).
# Store your key in an environment variable
export CX_API_KEY="your-actual-api-key"

# Reference it in your application
curl -X POST "https://cx2-main.pit.cxgp.us/cx/v2/action/setCustomer" \
  -H "CX-API-KEY: $CX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"givenName":"Ol","familyName":"Persson","primaryEmail":{"value":"ol.persson@example.com"}}'

Environments

The CX Platform provides separate environments to support your testing and release flow. Each environment is isolated — data, keys, and configurations do not cross environment boundaries.

Environment Base URL Purpose
PIT (Test) https://cx2-main.pit.cxgp.us Integration testing and validation
Production <supplied by CX representative> Live customer traffic

Test (sometimes called PIT - Partner Integration Testing)

  • Mirrors production behavior and configuration.
  • Use for integration testing and regression testing.
  • Data is periodically reset or managed by CX support team.

Production

  • Handles live customer data — treat with care.
  • Strict rate limits.
  • Requires production-grade API credentials issued by sales/support.

Environment-Specific Rate Limits

The Java SDK does not implement client-side throttling, automatic retries, or backoff. It sends requests directly and surfaces the HTTP response/error back to your application.

Environment Current implementation guidance Operational guidance SDK behavior
PIT (Test) Rate limits are managed on the platform side; the SDK does not include fixed rate-limit values. Use PIT for integration and regression testing only. Treat capacity as non-production and coordinate higher-volume testing with CX support. No automatic throttling or retry. Handle 429 and 5xx responses in your application.
Production Rate limits are managed on the platform side; the SDK does not include fixed rate-limit values. Production throughput is managed operationally. Confirm your expected traffic profile with sales/support before go-live. No automatic throttling or retry. Handle 429 and 5xx responses in your application.

What the SDK actually does

In the current Java SDK implementation, CxSdkClient delegates directly to the generated API client. It does not read rate-limit headers, it does not back off automatically, and it does not retry requests for you.

Credential Rotation and Expiration

  • API keys are issued outside the SDK and passed into CxSdkClient at construction time.
  • Key rotation and revocation requests are handled by the CX Platform support team.
  • The current Java SDK implementation does not expose a self-service rotation endpoint or a field that tells you when a key will expire.
  • If a key becomes invalid, revoked, or expired according to server-side policy, expect authentication failures such as 401 Unauthorized or 403 Forbidden.
  • When rotating credentials in your integration, update the stored secret in your configuration system and create a new CxSdkClient with the replacement key. If needed, you can also update the key on an existing client via setApiKey(...).

OAuth 2.0 Support Status

For standard CX API requests, the current Java SDK implementation supports API key authentication using the CX-API-KEY header.

  • The CX REST API examples on this site should use the raw API key value in CX-API-KEY.
  • OAuth 2.0 is not currently used by the Java SDK client for inbound CX API calls.

Webhook Request Validation

Webhook delivery authentication is separate from authenticating your calls into CX.

  • The current Java SDK does not provide webhook receiver utilities or signature verification helpers.
  • The current Java SDK implementation does not provide webhook signature verification behavior.
  • If you expose a webhook endpoint, secure it with HTTPS and validate the delivery mechanism configured for your integration (for example, OAuth 2.0, bearer token, or relayed CX-API-KEY) in coordination with CX support.
  • If you need cryptographic signature verification, treat that as a separate integration requirement and confirm the supported approach with CX before implementation.

Switching Environments

To switch environments, simply change the base URL and cx api key — the API surface and authentication mechanism are identical across all environments.

# PIT (Test)
 curl -X POST "https://cx2-main.pit.cxgp.us/cx/v2/action/setCustomer" \
  -H "CX-API-KEY: $CX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"givenName":"Ol","familyName":"Persson","primaryEmail":{"value":"ol.persson@example.com"}}'

# Production
 curl -X POST "{production_host_url}/cx/v2/action/setCustomer" \
  -H "CX-API-KEY: $CX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"givenName":"Ol","familyName":"Persson","primaryEmail":{"value":"ol.persson@example.com"}}'

// PIT (Test)
CxSdkClient testClient = new CxSdkClient.Builder()
    .apiKey(System.getenv("CX_API_KEY"))
    .baseUrl("https://cx2-main.pit.cxgp.us")
    .build();

// Production
CxSdkClient prodClient = new CxSdkClient.Builder()
    .apiKey(System.getenv("CX_API_KEY"))
    .baseUrl(System.getenv("CX_BASE_URL"))
    .build();

Configuration Pattern

Externalize the CX API key and base URL in your application configuration, then pass those values into the SDK builder:

The baseUrl value should remain the environment host only. Do not append /cx/v2 when configuring the Java SDK.

# application.properties
cx.base-url=${CX_BASE_URL:https://cx2-main.pit.cxgp.us}
cx.api-key=${CX_API_KEY}

CxSdkClient client = new CxSdkClient.Builder()
    .baseUrl(appConfig.getCxBaseUrl())
    .apiKey(appConfig.getCxApiKey())
    .build();

Next Steps