Authentication

Send the credential issued for your integration unchanged as a Bearer token from your backend:

Authorization: Bearer YOUR_ISSUED_API_KEY

Store it in AGGREGATOR_API_KEY or your secret manager. The placeholder is not a credential and does not select an environment or change permissions. Confirm organization access and the applicable credential policy with your account contact; available key-management controls depend on your deployment.

Key format and rollout

Deployment-dependent guidance: after the unified-key issuer rollout is enabled for your deployment, new operator keys use agg_ followed by 43 Base62 characters (0–9, A–Z, a–z).

This format description does not establish that the rollout is active on production. Use the key actually issued for your integration. Never edit its prefix, convert a historical key, or infer its environment, permissions or lifetime from an example. Existing credentials follow the status and lifecycle policy applicable to their deployment.

Replacing a key

Plan replacement with the key-management controls available to your organization:

1. Obtain a replacement credential for the intended organization and integration. Confirm its permissions and any applicable issuance limit.
2. Store the new credential in your secret manager.
3. Validate it with a permitted request before moving traffic. Confirm the replacement procedure allows any overlap you need.
4. Update all callers, verify successful use, and revoke the old credential. Confirm the old credential is rejected.

Do not rely on an automatic overlap window, indefinite validity, or historical expiry fields being ignored. Follow your deployment’s lifecycle policy and your organization’s security policy. Revoke a suspected compromised key immediately and arrange a replacement.

Rate limits

Use the rate-limit and Retry-After headers supplied by the response. When present, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset describe the applicable budget; the reset value is a Unix timestamp. Do not assume that every limiting response includes every header.

Limits, window algorithms, budget ownership and storage-failure behavior depend on the deployed policy. Confirm capacity for your integration instead of assuming separate read/write budgets or particular per-key, per-user or per-IP defaults. Retry only operations whose idempotency contract permits it, and respect the supplied delay.

Permissions

Confirm the organization, resources, operations and any IP restrictions authorized for the issued credential. A replacement does not imply the same custom permissions as another key. The key’s text and the examples in these docs do not grant access.

Security best practices

• Never commit keys to git. Use environment variables or a secret manager.
• Never expose API keys in browser-side code. Call the Machine API from your backend.
• Revoke on suspected compromise. Do not wait for an assumed expiry or replacement window.
• Separate integrations where supported. Use named credentials with appropriate permissions and track their callers.
• Treat real-money validation as real money movement. Confirm provider access, callback configuration and any agreed funding before creating a session. See Environments & testing.