Skip to content
Help Center Guide · Quick Start
4 min readVerified 2026-11-16

Set Up Your Account

Create your workspace, configure organization identity, and prepare wallet signing prerequisites before publishing.

In This Guide

Overview

Setting up a Passinstance account initializes your isolated tenant workspace, configures your regional preferences, and guides you through an automated onboarding pipeline to generate ready-to-test demo passes for Apple Wallet and Google Wallet.

Onboarding Pipeline & State Machine

Passinstance manages account initialization via an automated OnboardingSession state machine backed by the Onboarding API:

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
ONBOARDING STATE MACHINE
STAGE 01 WALLET_SETUP
Accept terms & provision Google
STAGE 02 PERSONALIZE
Choose volume & use-case catalog
STAGE 03 GENERATING_DEMOS
Asynchronous background j job builds 17 templates
STAGE 02A DONE
Production ready; launch templates
STAGE 02B TRY_PASS
Scan sample pass on iOS / Android
STAGE 02C GENERATING_DEMOS
Background generation finishes demo catalog

Onboarding Steps & Enums

The session transitions through the exact OnboardingStep enum values:

  1. 1
    WALLET_SETUP: Review and accept platform wallet issuance terms (googleWalletAccepted) and prepare default demo credentials.
  2. 2
    PERSONALIZE: Select your business model and anticipated monthly volume tier:

- EVALUATING: Testing capabilities and sandbox exploration. - UP_TO_500: Boutique stores, local clubs, specialized venues. - RANGE_500_5000: Growing retailers, regional gyms, medium events. - RANGE_5000_25000: Multi-location franchises and large membership associations. - RANGE_25000_PLUS / ENTERPRISE: High-volume ticketing, national retail loyalty, airline/transit passes.

  1. 3
    GENERATING_DEMOS: The backend enqueues background jobs that provision demo templates across OnboardingUseCase categories (LOYALTY_AND_CUSTOMER_CARDS, MEMBERSHIP_CARDS, TICKETING, VOUCHERS_OR_COUPONS, GIFT_CARDS_OR_PREPAID_CARDS, BUSINESS_CARDS, EMPLOYEE_IDS, INSURANCE_WARRANTY_AND_SERVICE_CARDS, OTHER).
  2. 4
    TRY_PASS: Generates an ephemeral sample pass with a scannable QR code for instant phone installation.
  3. 5
    DONE: Onboarding concludes and unlocks the full administrative dashboard (/dashboard).

Onboarding Controller API Reference

Developers and automated provisioning scripts can drive onboarding programmatically under /api/v1/onboarding:

Endpoint PathMethodAuthPayload / ParametersDescription
/api/v1/onboardingGETBearerNoneRetrieves current onboarding session state, active step, and generated demos.
/api/v1/onboarding/wallet-setupPUTBearer{ "googleWalletAccepted": true }Accepts wallet issuance terms and provisions default Google Wallet setup.
/api/v1/onboarding/personalizePUTBearer{ expectedPassVolume, useCases: [] }Stores business volume tier and selected OnboardingUseCase items.
/api/v1/onboarding/demosPOSTBearerNoneTriggers async generation of demo templates (QUEUED -> READY).
/api/v1/onboarding/demosGETBearerNonePolls demo generation progress across requested use cases.
/api/v1/onboarding/demos/:type/retryPOSTBearerURL param :typeRetries demo template generation if a specific catalog type failed.
/api/v1/onboarding/sample-passPOSTBearer{ templateId? }Generates a live test pass for immediate wallet installation.
/api/v1/onboarding/sample-pass/public/:sessionIdGETNoneURL param :sessionIdUnauthenticated public endpoint to view/install the sample pass on mobile.
/api/v1/onboarding/completePOSTBearer{ skipSamplePass?: boolean }Marks the onboarding session as DONE.

Account Setup Checklist

Follow these milestones in Passinstance Dashboard to prepare your workspace for production launch:

  1. 1
    Verify Workspace & Email: Confirm your email address (any valid email works) upon registration to establish your administrative tenant credentials, pre-provisioned with a Demo Apple Certificate and Managed Google Wallet Issuer.
  2. 2
    Configure Regional Settings: Visit Settings -> General (/settings/workspace/general) or call PUT /api/v1/customer/:customerId/regional-settings to configure:

- Timezone: Evaluates daily scan caps and local timestamps (e.g. Europe/Berlin, America/New_York). - Currency: Sets default ISO 4217 currency for prepaid balances (e.g. EUR, USD, GBP). - Default Language: Sets primary language for localized wallet fields.

  1. 3
    Configure Apple Wallet Certificate (Production): In Settings -> Wallet -> Apple Certificates (/settings/workspace/wallet), generate a Certificate Signing Request via POST /api/v1/certificates/generate-csr, upload it to the Apple Developer Portal under Pass Type IDs, and import the signed .cer file via POST /api/v1/certificates.
  2. 4
    Configure Google Wallet Issuer (Production): Under Settings -> Wallet -> Google Wallet, run setup (POST /api/v1/google-wallet/setup) and check status (GET /api/v1/google-wallet/status) to inspect your Google Issuer ID and Smart Tap collectorId.
  3. 5
    Team Roles & Access Control: Under Settings -> Access -> Members & Roles (/settings/workspace/access), invite staff using organization roles (OrganizationMemberRole: OWNER, ADMIN, MEMBER) alongside workspace RBAC roles (DEFAULT_ROLES: super-admin, admin, editor, user, customer) and enforce Two-Factor Authentication (enforceTwoFactorAuth).

Prerequisites: To issue custom-branded production passes in Apple Wallet, you must have an active Apple Developer Program membership ($99/year) to generate an Apple Pass Type ID certificate (pass.com.yourcompany.app). Testing during the onboarding sandbox uses Passinstance demo certificates.

Review our available Plans & Capacity Tiers or proceed directly to Phase 2: Design Your Pass.

Related Product & Developer Documentation

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.