Mobile Wallet API

Before You Begin

Before committing to a custom integration, consider Embed's out-of-the-box white-labelled web portal called Mobile Portal. It lets guests create accounts, register cards, check balances, and reload online — with no custom development required. You can customise the branding to match your own. If Mobile Portal meets your requirements, it will be faster and cheaper than a custom integration. Speak to an Embed team member to find out more.

Prerequisites

All three of the following must be in place before you make your first API call.

Configure TOOLKIT Portal

TOOLKIT Portal is the administration area for Mobile Wallet. Embed will provision your account. Log in at https://toolkit.helixleisure.net.

Get Your Client Secret

The Client Secret is used to obtain admin access tokens for the API. It is provisioned by Embed as part of the Mobile Wallet API setup process.

1. Log in to TOOLKIT Portal at https://toolkit.helixleisure.net.
2. Navigate to API Integration in the left-hand menu.
3. Locate the guest-portal module row and click Show Key.
4. Copy the key — this is your Client Secret.

First API Call: Register a Guest

All guests must be registered with Embed before using your application. Registration creates a guest account and links it to at least one physical game card.

Requirements

• Guest email address (used as the username — must be unique)
• Game card 10-digit barcode and 3-digit CVV
• The game card must already be activated in TOOLKIT (any in-store activity such as adding a balance activates it automatically)

Password rules

Sign-up request

POST /api/v1/admin/signup
Authorization: Bearer <admin_jwt_token>

{
  "username":     "guest@example.com",
  "password":     "SecurePass1",
  "firstName":    "Jane",
  "lastName":     "Smith",
  "cardBarcode":  "1234567890",
  "cardCvv":      "123",
  "cardNickname": "My Blue Card"
}

Next Steps

With configuration complete and your first guest registered, you are ready to build out the remaining flows:

Overview

The Mobile Wallet API uses Bearer Authentication with JWT (JSON Web Tokens). Every API request must include a valid access token in the Authorization header:

Authorization: Bearer <access_token>

There are two distinct token levels — an admin access token and a guest (Cognito) access token — each used for different operations. You must obtain them in sequence before any guest-level API calls can be made.

Token Types

Step 1 — Get Your Client Secret

The Client Secret is provisioned by Embed as part of the Mobile Wallet API setup. It is available in TOOLKIT Portal once your account has been configured.

1. Log in to TOOLKIT Portal at https://toolkit.helixleisure.net
2. Navigate to API Integration in the left-hand menu
3. Locate the guest-portal module row
4. Click Show Key to reveal the Client Secret value
5. Copy the key for use in your server-side environment

Step 2 — Get an Admin Access Token

Before a guest can sign up or log in, your server must obtain an admin access token by posting the Client Secret to the token endpoint.

POST /api/v1/token
Content-Type: application/json

{
  "clientSecret": "<your_client_secret>"
}

// Response
{
  "accessToken": "<admin_jwt_token>"
}

Step 3 — Register a Guest (Sign-up)

All guests must be registered with Embed before they can log in. Registration links a guest account to at least one physical game card.

Requirements

• Guest's email address — used as the username and must be unique
• Game card 10-digit barcode and 3-digit CVV
• The game card must already be activated in the on-premise TOOLKIT system

Password rules

POST /api/v1/admin/signup
Authorization: Bearer <admin_jwt_token>
Content-Type: application/json

{
  "username":     "guest@example.com",
  "password":     "SecurePass1",
  "firstName":    "Jane",
  "lastName":     "Smith",
  "cardBarcode":  "1234567890",
  "cardCvv":      "123",
  "cardNickname": "My Blue Card"
}

// Response 201 Created
{ "message": "Guest account created successfully" }

Step 4 — Guest Login

Once a guest is registered, they log in using their email address and password. A successful login returns both a Cognito access token and a refresh token.

POST /api/v1/admin/login
Authorization: Bearer <admin_jwt_token>
Content-Type: application/json

{
  "username": "guest@example.com",
  "password": "SecurePass1"
}

// Response 200 OK
{
  "accessToken":  "<cognito_access_token>",
  "refreshToken": "<refresh_token>"
}

Step 5 — Refresh an Expired Token

POST /api/v1/admin/token
Content-Type: application/json

{
  "refreshToken": "<refresh_token>"
}

// Response 200 OK
{ "accessToken": "<new_cognito_access_token>" }

Step 6 — Reset a Guest Password

// Step 6a — Trigger reset email
PUT /api/v1/admin/{emailAddress}/reset
// Returns 204 No Content. Guest receives email with confirmation code.

// Step 6b — Submit new password
PUT /api/v1/admin/{emailAddress}/confirmReset
Content-Type: application/json

{
  "confirmationCode": "123456",
  "newPassword":      "NewSecurePass1"
}
// Returns 204 No Content.

Authentication Flow Summary

1. Server  →  POST /api/v1/token               (Client Secret)
              ← 200: admin_access_token

2. Server  →  POST /api/v1/admin/signup         (admin_access_token + guest details + card)
              ← 201: Guest account created

3. Server  →  POST /api/v1/admin/login          (admin_access_token + email + password)
              ← 200: cognito_access_token + refresh_token

4. App     →  GET  /api/v1/card                 (cognito_access_token)
              ← 200: Guest card list

       [Token expires]

5. Server  →  POST /api/v1/admin/token          (refresh_token)
              ← 200: new cognito_access_token

Error Reference