API Keys, CORS and Audit Trail

This guide covers the developer-facing settings in the admin console: Advanced / Developer → API Keys for connecting your own systems to Babylon, the CORS Configuration and Platform Backend Routing sections on Settings → Business Settings → Advanced, and Advanced / Developer → Audit Trail, the tamper-evident record of live auction actions. For the endpoints themselves, see the API reference at /docs/.

Before you start

• API Keys needs API access to be included in your plan, and the manage api keys permission. The standard Admin role has the permission. If API access is not part of your plan, the API Keys screen does not appear at all; contact Hammerd support to discuss adding it.
• CORS Configuration and Platform Backend Routing are on Settings → Business Settings, which needs the manage tenant settings permission.
• Audit Trail needs live auctions to be included in your plan, and the view action logs permission. The Admin and Auctioneer roles have it.

See Team members and roles for how permissions are granted, and Platform billing and subscription for your plan.

API keys

API keys let your own server-side systems act on your account without a person signing in: a stock feed, a nightly reporting job, a data integration or a trusted third-party service.

API keys are for server-to-server use only. Never put a key in a web page, a mobile app or anything else a user can inspect, because anyone who can see the key can use it. Browser and app users should sign in with their own accounts instead.

Creating a key

1. Go to Advanced / Developer → API Keys.
2. Click New API Key.
3. Enter a Key Name that says what the key is for, for example "Nightly stock export".
4. Under Permissions, add only the permissions this integration needs. Start typing to see the suggestions (listed below). If you leave Permissions empty, the key gets full access (*), which is rarely what you want.
5. Optionally, open Security Settings and set an Expiration Date (leave it empty for a key that never expires) and an IP Whitelist of the addresses your integration calls from (leave it empty to allow any address).
6. Click Create.

Copying the key

After you create the key, Babylon opens the key's page and shows the full secret in a Your New API Key dialog and a Newly Created API Key panel. Copy it straight into your password manager or your server's secret store. When you close the dialog with I've copied it, close, the full key is not shown again on that page.

If you missed it, the key's page offers View API Key exactly once. Confirming with I understand, show the key reveals the key and then deletes the stored copy for good. After that, Plaintext Key Status reads "Already viewed on ..." and the only way to get a working secret is to rotate the key. Hammerd support cannot recover a key for you.

Keys start with sk_live_ on the production platform (you may see sk_test_ on test environments). The first part of each key, shown as Prefix in the list, identifies it without revealing the secret.

Permissions you can grant

The suggestions in Permissions are:

• Listings: listings:read, listings:write, listings:delete
• Auctions and bids: auctions:read, bids:create, bids:read
• Orders and payments: orders:read, orders:write, payments:read, payments:write
• Users: users:read, users:write
• Integrations: integrations:webhooks:read, integrations:webhooks:write, integrations:events:read, integrations:deliveries:read, integrations:replay:write, integrations:realtime:read
• Seller agreements: agreements:read, agreements:write
• Broad access: admin:* and * (everything). Avoid these unless you genuinely need them.

A key acts as the team member who created it, shown as Owner, and is limited to the permissions you gave the key. The API reference at /docs/ lists which permission each endpoint needs.

Using a key

Send the key as a bearer token in the Authorization header. Babylon also needs to know which account the request is for:

• If you call the API on your own storefront hostname, your account is identified from the hostname.
• If you call the API on Babylon's shared platform API host (the base URL given in the API reference), add an X-Tenant-ID header with your tenant ID. Your tenant ID is shown at the top of Settings → Communications, next to "tenant id".

Authorization: Bearer sk_live_...
X-Tenant-ID: {your-tenant-id}
Accept: application/json

A key only works for the account it was created in. A request whose account does not match the key is rejected, as is a request from an address outside the key's IP Whitelist, or one made with an expired or revoked key. Repeated failed attempts with a wrong key temporarily lock it out, and each key is rate limited; if you exceed the limit you receive a 429 response with a Retry-After header.

Managing keys

The API Keys list shows each key's name, Prefix, Owner, Permissions, Status (Active or Revoked), number of Requests, when it was last used and when it expires. Tabs across the top filter to All Keys, Active, Expired, Revoked and Recently Used (used in the last seven days). You can also filter by Owner, Status, expiry dates, last-used dates and permissions.

Open a key to see its details, including Usage Statistics (request count, last used time and address, failed attempts) and its Security settings.

• Rotate Key (from the row's More actions menu) revokes the key immediately and issues a replacement with the same permissions, expiry and IP whitelist. The new key is shown once on the next screen. Anything still using the old key starts failing at once, so update your integration straight away.
• Revoke Key (from More actions, or on the key's page) stops the key working immediately. You can fill in Reason (optional). Revoking cannot be undone; create a new key if you need access again.
• To revoke several keys at once, select them in the list and choose Revoke Selected.

Rotate or revoke a key straight away if you think it has been exposed, and when a team member who owns keys leaves.

CORS configuration

CORS (cross-origin resource sharing) controls which websites a browser will allow to call the Babylon API directly, for example your own custom frontend or a staging copy of your site. It only matters for code running in a browser; server-to-server calls with an API key are not affected.

Find it on Settings → Business Settings, Advanced tab, CORS Configuration section.

• Your primary storefront hostname is allowed automatically. The help text under the field shows which one, for example "Your primary hostname is auto-allowed: https://auctions.example.com". If you have not connected a hostname yet, it says so.
• Add anything else to Additional Allowed Origins. Type an origin and press Enter to add it.

Rules for each origin:

• Enter the scheme and hostname only, for example https://staging.example.com. Include a port only if your site uses one, for example http://localhost:3000 for local development.
• No trailing slash and no path. A trailing slash is removed for you; a path will never match a browser's origin, so leave it off.
• Only http:// and https:// origins are accepted. Use https:// for anything other than local development.
• Wildcards such as * are not accepted.
• You can add up to 20 additional origins.

An invalid entry shows an error such as "Invalid origin URL: ..." when you save. Click Save Settings at the bottom of the page to apply your changes. Remove origins you no longer use, especially old staging sites.

Platform Backend Routing

Also on the Advanced tab, Platform Backend Routing has one setting, Platform Backend Base. It chooses which family of Babylon platform hosts your account's API, bidding, uploads and realtime updates use. It does not affect your storefront domain.

Leave this at its default unless Hammerd support asks you to change it. Changing it can break integrations and apps that expect the current hosts.

Audit Trail

Advanced / Developer → Audit Trail is a read-only, append-only record of actions taken while running live auctions: starting, pausing, resuming, hammering and passing lots, accepting floor bids, and bids resolved by fairness arbitration. Each entry carries a checksum so any tampering can be detected; if the record fails its integrity check, the screen will not display it. Entries cannot be edited or deleted, and there is no way to create one by hand.

The list shows, for each entry:

• ID: the entry's reference, which you can copy.
• Action Type: for example lot.start, lot.hammer, lot.pause, lot.resume, lot.pass, bid.accept or bid.arbitrated.
• Actor: who performed the action.
• Command ID and Event ID: the command that caused the action and the live auction event it belongs to.
• Executed At: when it happened. The newest entries come first, 50 to a page.
• Checksum: the integrity fingerprint for the entry.

Use the filters to narrow the list by Action Type (Lot Start, Lot Hammer, Lot Pause, Lot Resume, Lot Pass, Bid Accept, Bid Arbitrated) or by Event. Click the view icon on any row to open the full entry, including the actor's name and email, the Action Payload and any Metadata.

The Audit Trail does not record general admin activity such as settings changes, API key creation or listing approvals. If you need a record of those for a dispute or investigation, contact Hammerd support. If the screen shows Auction data is unavailable, the record could not be reached at that moment. It does not mean nothing happened. Refresh to try again, and contact Hammerd support if it keeps failing.

Common questions

I cannot see API Keys in the sidebar. Either API access is not part of your plan, or you do not have the manage api keys permission. Ask an administrator, or contact Hammerd support about your plan.

My integration gets "Invalid tenant context". The request did not say which account it was for. Add the X-Tenant-ID header when calling the shared platform API host.

My integration gets "Invalid API key". Check the key has not been revoked, rotated or expired, that the request comes from an address on its IP Whitelist, and that the X-Tenant-ID header matches the account the key belongs to.

My browser app is blocked by CORS. Check that the exact origin shown in the browser's address bar (scheme, hostname and any port) is in Additional Allowed Origins, with no trailing slash, and that you saved the page.

Where do webhooks fit in? Stripe webhooks are covered in Configuring Stripe webhooks.