Auth API

The Auth API handles user registration, login, session management, and embedded iframe authentication. It supports two authentication flows: direct auth (for standalone usage) andembed auth (for casino iframe integrations where the operator manages the user session).

Authentication Flows

Predictu supports two distinct authentication flows depending on how the user accesses the platform.

Direct Authentication

Used when users access Predictu directly (not through a casino embed). Users register with an email and password, then log in to receive a session token.

Embed Authentication

Used when users access Predictu through a casino operator’s iframe embed. The operator passes a signed token from their system, and Predictu either finds an existing user or creates one automatically.

Login

Authenticates a user with email and password. Returns a JWT session token on success. This endpoint is rate-limited to prevent brute-force attacks.

Request Body

{
  "email": "alice@example.com",
  "password": "s3cur3P@ssw0rd"
}

Response (200 OK)

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2025-03-19T14:32:00.000Z",
  "user": {
    "id": "usr_def456",
    "email": "alice@example.com",
    "username": "alice",
    "tier": "regular",
    "operator_id": "op_abc123",
    "created_at": "2025-01-15T10:00:00.000Z"
  }
}

Error Responses

Security Notes

• Passwords are hashed with bcrypt (cost factor 12) and never stored in plaintext
• Failed login attempts are logged with IP address and user agent for security auditing
• The error message for wrong email vs. wrong password is intentionally identical (INVALID_CREDENTIALS) to prevent email enumeration
• Successful login clears the failed attempt counter for that email

Register

Creates a new user account. The user is assigned to the new tier by default and receives an initial balance of $0. If an operator_id is provided, the user is associated with that operator.

Request Body

{
  "email": "alice@example.com",
  "password": "s3cur3P@ssw0rd",
  "username": "alice",
  "operator_id": "op_abc123"
}

Response (201 Created)

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2025-03-19T14:32:00.000Z",
  "user": {
    "id": "usr_new789",
    "email": "alice@example.com",
    "username": "alice",
    "tier": "new",
    "operator_id": "op_abc123",
    "balance": 0.00,
    "created_at": "2025-03-18T14:32:00.000Z"
  }
}

Error Responses

Side Effects

When a user registers successfully, the following side effects occur:

• A row is inserted into the users table with tier new
• A default user_scores row is created with neutral metric values
• If operator_id is provided, the operator receives a USER_REGISTERED S2S callback
• The registration event is logged in the audit trail
• A session token is automatically generated (the user is logged in immediately)

Get Current User

Returns the profile of the currently authenticated user. This endpoint is used to verify that a session token is still valid and to fetch the latest user state (tier, balance, etc.).

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response (200 OK)

{
  "user": {
    "id": "usr_def456",
    "email": "alice@example.com",
    "username": "alice",
    "tier": "regular",
    "classification": "moderate",
    "operator_id": "op_abc123",
    "balance": 150.00,
    "open_positions_count": 3,
    "total_trades": 42,
    "created_at": "2025-01-15T10:00:00.000Z",
    "last_trade_at": "2025-03-18T14:32:01.000Z"
  }
}

Error Responses

Embed Init

Initializes an authenticated session for a user within a casino operator’s embedded iframe. This is the primary authentication mechanism for the B2B casino integration. The operator signs a JWT with their secret key containing the player’s identity, and Predictu verifies it and creates/finds the corresponding Predictu user.

Request Body

{
  "operator_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRvcl9pZCI6Im9wX2FiYzEyMyIsInBsYXllcl9pZCI6InBsYXllcl83ODkiLCJ1c2VybmFtZSI6ImFsaWNlIiwiZXhwIjoxNzEwNzc1OTIxfQ.signature"
}

Operator Token Format

The operator JWT must contain the following claims:

{
  "operator_id": "op_abc123",     // Required: the operator's ID in Predictu
  "player_id": "player_789",      // Required: the player's ID in the operator's system
  "username": "alice",             // Optional: display name (used if creating new user)
  "email": "alice@example.com",   // Optional: email (used if creating new user)
  "exp": 1710775921               // Required: expiry timestamp (max 5 minutes from now)
}

Response (200 OK)

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2025-03-19T14:32:00.000Z",
  "user": {
    "id": "usr_embed_abc",
    "username": "alice",
    "tier": "new",
    "operator_id": "op_abc123",
    "external_player_id": "player_789",
    "balance": 0.00,
    "is_new": true,
    "created_at": "2025-03-18T14:32:00.000Z"
  }
}

The is_new field indicates whether this call created a new user (true) or found an existing one (false). This is useful for the operator to know when to trigger onboarding flows or welcome bonuses.

User Matching Logic

When /embed-init is called, the system uses the following logic to find or create the user:

Error Responses

Security Considerations

• Signature verification: The operator token is verified against the operator’s secret key stored in Predictu’s database. HMAC-SHA256 is the required algorithm.
• Origin check: In addition to token verification, the request’sOrigin or Referer header is checked against the operator’s whitelisted origins. This prevents a stolen operator token from being used on an unauthorized domain.
• Idempotency: Calling /embed-init multiple times with the sameoperator_id + player_id is safe. It always returns the same user (with a fresh Predictu token).
• No password: Embed users do not have passwords. They can only authenticate through the operator’s embed flow. They cannot use POST /login.

JWT Token Format

Predictu session tokens are standard JWTs with the following claims:

// Header:
{
  "alg": "HS256",
  "typ": "JWT"
}

// Payload:
{
  "sub": "usr_def456",           // User ID
  "email": "alice@example.com",  // User email (if available)
  "tier": "regular",             // User tier at time of token issuance
  "operator_id": "op_abc123",    // Operator (null for direct users)
  "role": "user",                // "user", "operator_admin", or "god_mode"
  "iat": 1710772321,             // Issued at
  "exp": 1710858721              // Expires at (24 hours later)
}

Rate Limits