Overview

The Developer Integration API allows external platforms to integrate with the poker engine, enabling seamless user provisioning, single sign-on (SSO) authentication, balance management, and real-time event notifications via webhooks. Partners authenticate server-to-server using HMAC-SHA256 signed API keys.

This API is designed for platform operators, affiliate networks, and third-party applications that want to embed poker functionality into their existing products. Users on your platform can be automatically provisioned with poker accounts and authenticated without creating separate credentials.

Partner endpoints are prefixed with /api/v1/developer and require HMAC-signed requests. The exceptions are POST /api/v1/developer/register, GET /api/v1/developer/status and the documentation pages under /api/v1/developer/docs, which are public. The browser-side code exchange lives outside that prefix at POST /api/v1/auth/exchange, and is public too.

Architecture Overview

┌─────────────────────┐         HMAC-Signed          ┌──────────────────────┐
│                     │ ─────── Requests ──────────── │                      │
│   Partner Backend   │                               │    Poker Engine      │
│                     │ ◄────── JSON Responses ────── │                      │
└────────┬────────────┘                               └───────────┬──────────┘
         │                                                        │
         │ 1. Generate login code                                 │
         │    POST /developer/auth/code                           │
         │                                                        │
         ▼                                                        │
┌─────────────────────┐                                           │
│                     │  2. Exchange code for session              │
│   Partner Frontend  │ ─────── POST /auth/exchange ─────────────►│
│   (User's Browser)  │                                           │
│                     │ ◄────── Session cookies/tokens ───────────│
└─────────────────────┘                                           │
                                                                  │
                              3. Webhook events                   │
┌─────────────────────┐ ◄──── HMAC-signed POST ──────────────────┘
│  Partner Webhook    │
│  Endpoint           │
└─────────────────────┘

Flow summary:

1. Your backend makes HMAC-signed API calls to provision users, manage balances, and generate login codes.
2. Your frontend exchanges a one-time login code to authenticate the user directly on the poker platform.
3. The poker engine sends signed webhook events to your backend when relevant actions occur (user changes, balance changes, deposits and withdrawals).

Table of Contents

Guide	Description
Quickstart	Get playing in 5 minutes — provision a user and log them in
Authentication	HMAC-SHA256 signing explained with examples in Node.js, Python, PHP, and cURL
SSO Integration	Single sign-on flow — cookie sessions vs. API tokens
User Provisioning	Create and manage poker accounts linked to your platform users
Balance Operations	Read and modify user balances with idempotent transactions
Webhooks	Subscribe to real-time events and verify webhook signatures
Error Reference	Complete list of error codes with causes and resolutions
Security Best Practices	API key storage, IP allowlisting, key rotation, and more
API Reference	Complete endpoint reference with schemas and examples

Available Scopes

Scopes control what actions an API key can perform. Assign the minimum scopes needed for your integration.

Scope	Description	Endpoints
user:create	Provision new users and update profiles	POST /developer/users, PUT /developer/users/:id
user:read	Read user details	GET /developer/users/:id
auth:code	Generate single-use login codes for SSO	POST /developer/auth/code
balance:read	Read user balances	GET /developer/users/:id/balance
balance:write	Credit and debit user balances	POST /developer/users/:id/balance/credit, POST /developer/users/:id/balance/debit
webhooks:manage	Subscribe to and manage webhook events	POST /developer/webhooks, GET /developer/webhooks, DELETE /developer/webhooks/:id

Supported Webhook Events

Event Type	Description
user.created	A new user was provisioned via the Developer API
user.updated	A user’s profile was updated via the Developer API
deposit.confirmed	A user’s deposit was confirmed
deposit.failed	A user’s deposit failed
withdrawal.completed	A user’s withdrawal was completed
withdrawal.failed	A user’s withdrawal failed
balance.credited	Balance was credited via the Developer API
balance.debited	Balance was debited via the Developer API

Getting Started

1. Obtain API credentials — Register as a partner via POST /developer/register (if self-registration is enabled) or contact the platform administrator.
2. Read the Quickstart — Provision your first user and generate a login code in under 5 minutes.
3. Implement HMAC authentication — All API calls from your backend must be signed.
4. Set up SSO — Choose cookie mode (browser session) or token mode (bearer tokens) for user authentication.
5. Subscribe to webhooks — Get real-time notifications for user, balance, deposit, and withdrawal events.

Rate Limits

Endpoint	Limit
POST /developer/register	5 per hour per IP
GET /developer/status	3 per minute per IP
POST /auth/exchange	10 per minute per IP
All HMAC-authenticated endpoints	Configurable per API key (default: 100 per minute)

When a rate limit is exceeded, the API returns HTTP 429 with the error code RATE_LIMIT_EXCEEDED. Responses to the per-key limit include a Retry-After header with the seconds to wait.

Feature Toggle

The Developer API is controlled by a platform-wide feature toggle (developerApi). When disabled, every endpoint except the documentation pages returns HTTP 403, including registration, the status check and POST /auth/exchange. The documentation endpoints remain accessible regardless of the toggle state, so you can read the docs before the feature is enabled.

{
  "success": false,
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "Feature 'developerApi' is currently disabled"
  }
}

The Developer API is part of the Enterprise license tier. On a lower tier the same endpoints return 403 with the code FEATURE_TIER_RESTRICTED.