Aggregator API

An authorized aggregator such as Pigmo can register each new casino as an independent OrbiSportbook client. The workflow is register → install wallet secrets → validate and activate → embed. Once the aggregator has automatic activation permission, individual clients do not need manual approval.

Download the OpenAPI 3.1 contract

One-time partner authorization

Open Aggregators in the platform Admin. Registration starts disabled. An MFA-authenticated platform administrator authorizes the partner directly. A second administrator is not required for aggregator authorization or key issuance. The policy specifies client quota, currencies, jurisdiction profiles, territories, exact HTTPS wallet origins, automatic activation permission, an approved agreement reference and an expiration within five years.

Issue a scoped aggregator key after authorization. It is displayed once to the issuing administrator. Keys expire within one year. Its expiry cannot exceed the authorization expiry. Store it only in the partner backend’s secret vault. Never distribute it to a casino browser, iframe, public deployment configuration or logs.

Scope	Capability
`clients:read`	List and read owned clients
`clients:create`	Provision clients and their two environments
`clients:activate`	Validate wallets and activate clients
`credentials:rotate`	Replace integration keys for one client environment

Authentication and retries

Base URL: https://api.orbisportbook.com/api/v1/aggregator.

Use Authorization: Bearer $AGGREGATOR_API_KEY. This server-to-server API does not use player login, staff cookies or X-Tenant-ID. Requests carrying Origin are rejected.

Every POST requires an Idempotency-Key containing 8–128 letters, digits, _, ., :, or -. Persist one key per operation and retry with the same body and API credential. Do not generate a new key for every attempt.

The encrypted original response can be replayed for 24 hours, with Idempotency-Replayed: true. A different body or API credential, or an expired response, produces 409. The request record remains to prevent an old retry from executing again. externalId is also unique within the aggregator. After expiry or conflict, read the client state and recover credentials from your vault before resuming; do not create another client to work around the response.

Limits: 64 KiB JSON bodies, 120 requests per minute per aggregator across its keys, and 100 clients per page. 429 responses include Retry-After: 60.

1. Register the casino

Wallet origins must be explicitly authorized. Production and sandbox must have different base URLs backed by separate balances. Wallet calls identify players through playerId; a tenant header is not a substitute for wallet environment isolation.

curl --fail-with-body https://api.orbisportbook.com/api/v1/aggregator/clients \
  -H "Authorization: Bearer $AGGREGATOR_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: casino-42-provision-v1' \
  -d '{
    "externalId": "casino-42",
    "name": "Casino 42",
    "legalName": "Casino 42 Ltd",
    "brandName": "Casino 42",
    "currency": "USD",
    "jurisdiction": "ROW",
    "locale": "en",
    "territories": ["CW"],
    "embedOrigins": ["https://casino42.example"],
    "productionWalletUrl": "https://wallet.partner.example/casino-42/production",
    "sandboxWalletUrl": "https://wallet.partner.example/casino-42/sandbox",
    "reason": "Casino deployment provisioning"
  }'

201 response (illustrative values):

{
  "id": "acl_generated",
  "externalId": "casino-42",
  "status": "suspended",
  "nextAction": "install_wallet_secrets_then_activate",
  "credentialsReplaySeconds": 86400,
  "production": {"tenantId":"ob_generated","walletSecret":"whsec_REDACTED_PRODUCTION"},
  "sandbox": {"tenantId":"ob_generated-sandbox","walletSecret":"whsec_REDACTED_SANDBOX"}
}

Internal IDs are server-generated; this API cannot claim an existing tenant. Save the client ID, environment tenant IDs and wallet secrets. Install each secret only in its respective wallet. Both environments initially remain suspended without usable integration API keys.

Implement all four wallet endpoints at each base URL. /balance must return an integer minor-unit balance and the registered currency. Reject invalid HMAC signatures with 401 or 403. Staging and production require public HTTPS on port 443 with a valid certificate. Private networks, cloud metadata, environment proxies and redirects are blocked during validation and subsequent financial calls. Only development allows HTTP loopback.

2. Validate and activate

Create a validation player in each of your wallet environments. OrbiSportbook only checks those players’ balances; this step does not create accounts or perform a debit, credit or rollback.

curl --fail-with-body \
  "https://api.orbisportbook.com/api/v1/aggregator/clients/$CLIENT_ID/activate" \
  -H "Authorization: Bearer $AGGREGATOR_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: casino-42-activate-v1' \
  -d '{"productionPlayerId":"validation-prod-42","sandboxPlayerId":"validation-sandbox-42","reason":"Validate deployed integration"}'

Both wallets must return the correct currency and reject an invalid signature. The service rechecks authorization, credential validity and integration configuration before activating. Revocation or configuration changes during the checks prevent activation and credential issuance. The deployment must have dedicated integration sandboxes enabled.

200 response:

{
  "id": "acl_generated",
  "status": "active",
  "credentialsReplaySeconds": 86400,
  "production": {"tenantId":"ob_generated","environment":"production","keyId":"key_generated_prod","integrationApiKey":"bki_production_REDACTED"},
  "sandbox": {"tenantId":"ob_generated-sandbox","environment":"sandbox","keyId":"key_generated_test","integrationApiKey":"bki_sandbox_REDACTED"}
}

Store each environment’s integration key separately. Use it as X-API-Key with the corresponding tenantId to create player sessions. Deliver only a launch token to the embedded browser.

This is technical activation under a pre-approved agreement, not certification of a license, data rights or complete financial homologation. Operator responsibilities and the go-live requirements still apply. A client subsequently suspended by the platform cannot reactivate itself through this endpoint.

Read and rotate

Method and path	Result
`GET /clients?limit=50&cursor=...`	Owned clients and `nextCursor`, without secrets
`GET /clients?externalId=casino-42`	Find a casino by the partner’s identifier
`GET /clients/{id}`	Environment IDs, currency, jurisdiction and status, without secrets
`POST /clients/{id}/credentials/rotate`	New integration key for the requested environment

For rotation send {"environment":"production","reason":"Scheduled rotation"} and a new idempotency key. All previous integration keys for that environment are revoked in the same transaction. This does not rotate wallet signing secrets or existing player sessions. Coordinate wallet signing-secret changes through the administrative integration workflow.

Revoking an aggregator key blocks new requests and replay access using that key. Disabling the aggregator blocks its API access while preserving existing client integrations and owed wallet payments. Casino suspension and casino credential revocation are separate actions.

Deployment job errors

HTTP	Handling
`400`	Correct the body, wallet response, currency, signature or deployment configuration
`401`	Expired/revoked key or disabled/expired authorization; stop and review access
`403`	Scope, currency, territory, origin or activation permission not granted
`404`	Client does not exist or belongs to another aggregator
`409`	Read state: duplicate, quota, incompatible retry, changed configuration or completed activation
`429`	Respect `Retry-After` and repeat with the same idempotency key
`5xx` / timeout	Retry with backoff and the same key; do not assume the operation did not commit

For Pigmo, persist a per-casino job with registered, wallet_secrets_installed, validated and integrated stages. Store redacted receipts in logs and secrets in the vault before advancing. Enable the sportsbook for players only after saving the integration keys and completing iframe testing.