# PERS-api Documentation **PERS API Documentation** This RESTful API enables seamless integration of Web3 loyalty, token management, and engagement features into your applications. **Usage Guidelines:** - **RESTful Design**: Resources are accessed via standard HTTP methods (GET, POST, PUT, DELETE) with predictable, resource-oriented URLs. - **Authentication**: Secure access is enforced via Bearer Tokens (JWT) and Project Keys (defining the Tenant context). - **Data Format**: All requests and responses utilize standard JSON formatting. Explore the modules below for detailed endpoint specifications, schemas, and testing capabilities. --- ### Error Handling All API errors follow RFC 7807 (Problem Details for HTTP APIs) with a `StructuredError` schema. See the **Schemas** section below for the full structure. Version: 2.3.8 ## Servers ``` https://api.pers.ninja/v2 ``` ## Security ### authJWT Authentication JWT token for user/business/admin/system access Type: http Scheme: bearer Bearer Format: JWT ### projectKey Project API key Type: apiKey In: header Name: x-project-key ## Download OpenAPI description [PERS-api Documentation](https://docs.pers.ninja/_bundle/swagger.yaml) ## Tenants ## Tenant Management
Tenant management for multi-tenant PERS loyalty platform. Each tenant represents a business or organization running their own reward program with dedicated data isolation and configuration.
Core Features:
•Multi-Tenant Architecture: Complete data isolation between tenant organizations
•Tenant Configuration: Custom settings, branding, and program rules per tenant
•Admin Dashboard Access: Comprehensive management interface for tenant administrators
•Data Security: Highest level confidentiality and security per tenant environment
•API Integration: Seamless integration with existing business systems ### Create new tenant - [POST /tenants](https://docs.pers.ninja/swagger/tenants/tenantscontroller_createtenant.md): Create a new tenant (project) in the system. This is the initial setup step for new organizations. ### Update tenant configuration - [PUT /tenants](https://docs.pers.ninja/swagger/tenants/tenantscontroller_updatetenant.md): ADMIN: Update tenant information and settings ### Get client configuration - [GET /tenants/client-config](https://docs.pers.ninja/swagger/tenants/tenantscontroller_getclientconfig.md): Retrieve client-side configuration for the project ### Get login token - [GET /tenants/login-token](https://docs.pers.ninja/swagger/tenants/tenantscontroller_getlogintoken.md): Generate a login token for the project ### Get current tenant information - [GET /tenants/me](https://docs.pers.ninja/swagger/tenants/tenantscontroller_getcurrenttenant.md): Context-aware endpoint for retrieving your own tenant information. REQUIREMENTS: - Header: x-project-key (project identification) - Optional: Authorization Bearer token (for full access) RETURNS: - With API Key only: Public tenant information - With Tenant JWT: Full tenant information including allowedTokenIssuers and sensitive config ### Get tenant information by ID - [GET /tenants/{id}](https://docs.pers.ninja/swagger/tenants/tenantscontroller_gettenantbyid.md): Context-aware tenant information retrieval: UNAUTHENTICATED ACCESS: - No headers required - Returns: Basic public tenant information ## Admins ## Administrative Management
Administrative user management for tenant administrators. Handles admin authentication, permissions, and tenant-level administrative operations with secure access controls.
Admin Features:
• Admin Authentication: Secure admin login and session management
• Permission Management: Role-based access control for administrative functions
• Tenant Administration: Full tenant configuration and management capabilities
• Security Controls: Enhanced security measures for administrative access
• Multi-Level Access: Support for different administrative privilege levels ### Get current admin profile - [GET /admins/me](https://docs.pers.ninja/swagger/admins/adminscontroller_getcurrentadmin.md): ADMIN: Retrieve the currently authenticated admin profile ### Get all admins - [GET /admins](https://docs.pers.ninja/swagger/admins/adminscontroller_getadmins.md): ADMIN: Retrieve all admins associated with the current tenant. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). ### Create or update admin - [POST /admins](https://docs.pers.ninja/swagger/admins/adminscontroller_createorupdateadmin.md): ADMIN: Create a new admin or update an existing admin within the tenant scope ### Toggle admin-tenant association - [PUT /admins/{adminId}/tenant](https://docs.pers.ninja/swagger/admins/adminscontroller_toggleadmintenantassociation.md): ADMIN: Associate or disassociate the specified admin with the current tenant. This affects admin tenant access. ## Tokens ## Token Management System
Token system for PERS loyalty platform managing various token types including Credits, Rewards, and Status tokens. Provides comprehensive token lifecycle management from creation to redemption.
Token Operations:
• Token Creation: Define custom token types with specific properties and rules
• Token Distribution: Mint and distribute tokens to users through campaigns
• Balance Management: Track token balances across user accounts
• Token Transfer: Enable token transfers between users when configured
• Token Burning: Remove tokens from circulation for deflationary mechanics
Token Module ### Get all token contracts - [GET /tokens](https://docs.pers.ninja/swagger/tokens/tokenscontroller_getalltokens.md): Retrieve all token contracts for the project. Only admins can access inactive tokens via ?active=false parameter. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). ### Create new token contract - [POST /tokens](https://docs.pers.ninja/swagger/tokens/tokenscontroller_createtoken.md): ADMIN: Create a new testnet token contract for the project. This can later be converted to mainnet. ### Get token by contract address - [GET /tokens/address/{contractAddress}](https://docs.pers.ninja/swagger/tokens/tokenscontroller_gettokenbyaddress.md): Retrieve token information by contract address ### Get active point token - [GET /tokens/points](https://docs.pers.ninja/swagger/tokens/tokenscontroller_getactivepointtoken.md): Retrieve the active point token contract for the project ### Get all reward tokens - [GET /tokens/rewards](https://docs.pers.ninja/swagger/tokens/tokenscontroller_getrewardtokens.md): Retrieve all reward token contracts (ERC1155 tokens). Only admins can access inactive tokens via ?active=false parameter. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). ### Get all stamp tokens - [GET /tokens/stamps](https://docs.pers.ninja/swagger/tokens/tokenscontroller_getstamptokens.md): Retrieve all stamp token contracts (ERC721 tokens). Only admins can access inactive tokens via ?active=false parameter. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). ### Get all token types - [GET /tokens/types](https://docs.pers.ninja/swagger/tokens/tokenscontroller_getalltokentypes.md): Retrieve all available token types for the project. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). ### Create new token type - [POST /tokens/types](https://docs.pers.ninja/swagger/tokens/tokenscontroller_createtokentype.md): ADMIN: Create a new token type for the project ### Update token contract - [PUT /tokens/{id}](https://docs.pers.ninja/swagger/tokens/tokenscontroller_updatetoken.md): ADMIN: Update token contract information ### Toggle token active status - [PUT /tokens/{id}/status](https://docs.pers.ninja/swagger/tokens/tokenscontroller_toggletokenstatus.md): ADMIN: Toggle token active status to enable/disable usage ### Set mainnet contract address - [PUT /tokens/{id}/mainnet](https://docs.pers.ninja/swagger/tokens/tokenscontroller_setmainnetcontract.md): ADMIN: Associate mainnet contract address with existing testnet token ### Create token metadata - [POST /tokens/{id}/metadata](https://docs.pers.ninja/swagger/tokens/tokenscontroller_createtokenmetadata.md): ADMIN: Create metadata for a specific token contract ### Update token metadata - [PUT /tokens/metadata/{metadataId}](https://docs.pers.ninja/swagger/tokens/tokenscontroller_updatetokenmetadata.md): ADMIN: Update metadata for a specific token. ERC721: only affects future mints. ERC1155: ⚠️ updates ALL existing minted tokens (shared base URI). ### Toggle token metadata status - [PUT /tokens/metadata/{metadataId}/status](https://docs.pers.ninja/swagger/tokens/tokenscontroller_toggletokenmetadatastatus.md): ADMIN: Toggle token metadata active status ## Campaigns ## Core Campaign Management
Core campaign CRUD operations with intelligent access detection. Handles campaign lifecycle management including creation, updates, activation, and querying with role-based access control.
Campaign Operations:
• Campaign Discovery: Public browsing of active campaigns without authentication
• Advanced Filtering: Query campaigns by tags, status, and custom criteria
• Lifecycle Management: Full campaign CRUD with proper state transitions
• Environment Control: Toggle campaigns between testnet and mainnet modes
• Access Intelligence: Automatic privilege detection for appropriate data exposure
Campaign Module ### Get campaigns (Intelligent Access) - [GET /campaigns](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_getcampaigns.md): Endpoint that adapts based on authentication: Public users get active campaigns with filtering, Business users get all campaigns (active+inactive) for their business only, Admin users get all campaigns with full filtering. Use pagination parameters (page & limit) for optimal performance - critical for large campaign datasets. Legacy support: returns array without params (deprecated - will be removed in future). Replaces GET /campaign and GET /campaign/admin ### Create campaign (Admin) - [POST /campaigns](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_createcampaign.md): Create a new campaign. Admin-only operation. Replaces POST /campaign/admin/ ### Get campaign by ID - [GET /campaigns/{id}](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_getcampaignbyid.md): Get single campaign details by ID. Available to public with project key. Replaces GET /campaign/{id} ### Update campaign (Admin) - [PUT /campaigns/{id}](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_updatecampaign.md): Update an existing campaign. Admin-only operation. Replaces PUT /campaign/admin/{id} ### Delete campaign (Admin) - [DELETE /campaigns/{id}](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_deletecampaign.md): Delete an existing campaign. Admin-only operation. Replaces DELETE /campaign/admin/{id} ### Toggle campaign status (Admin) - [PUT /campaigns/{id}/status](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_togglecampaignstatus.md): Toggle campaign active/inactive status. Admin-only operation. Replaces PUT /campaign/admin/{id}/activate ### Toggle campaign environment (Admin) - [PUT /campaigns/{id}/environment](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_togglecampaignenvironment.md): Toggle campaign between testnet and mainnet environment. Admin-only operation. Replaces PUT /campaign/admin/{id}/environment ### Assign trigger source to campaign (Admin) - [PUT /campaigns/{id}/trigger-sources/{triggerSourceId}](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_assigntriggersourcetocampaign.md): Assign a trigger source to a specific campaign. Admin-only operation. ### Remove trigger source from campaign (Admin) - [DELETE /campaigns/{id}/trigger-sources/{triggerSourceId}](https://docs.pers.ninja/swagger/campaigns/campaignscontroller_removetriggersourcefromcampaign.md): Remove a trigger source assignment from a specific campaign. Admin-only operation. ## Campaign Tags ## Campaign Organization System
Campaign tagging system for organization and categorization. Enables efficient campaign discovery through tag-based filtering and provides comprehensive tag management.
Tag Management:
• Tag Discovery: Browse all unique tags across campaign catalog
• Campaign Tagging: Associate multiple descriptive tags with campaigns
• Tag-Based Filtering: Enhanced campaign search and discovery via tags
• Tag Administration: Complete tag CRUD operations for administrators
• Organization Tools: Categorize campaigns by business criteria and themes ### Get all unique campaign tags (Admin) - [GET /campaigns/{campaignId}/tags](https://docs.pers.ninja/swagger/campaign-tags/campaigntagscontroller_getalluniquetags.md): Get all unique tags used across all campaigns. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). Admin-only operation for tag management. Set campaignId to "all" to retrieve tags from all campaigns. ### Update campaign tags (Admin) - [PUT /campaigns/{campaignId}/tags](https://docs.pers.ninja/swagger/campaign-tags/campaigntagscontroller_updatecampaigntags.md): Replace all tags for a campaign with new tag list. Admin-only operation. Replaces PUT /campaign/admin/{id}/tags ### Add tags to campaign (Admin) - [POST /campaigns/{campaignId}/tags](https://docs.pers.ninja/swagger/campaign-tags/campaigntagscontroller_addtagstocampaign.md): Add new tags to existing campaign tags without removing existing ones. Admin-only operation. Replaces POST /campaign/admin/{id}/tags ### Remove tag from campaign (Admin) - [DELETE /campaigns/{campaignId}/tags/{tag}](https://docs.pers.ninja/swagger/campaign-tags/campaigntagscontroller_removetagfromcampaign.md): Remove a specific tag from campaign while preserving other tags. Admin-only operation. Replaces DELETE /campaign/admin/{id}/tags/{tag} ## Campaign Tokens ## Campaign Reward Configuration
Token unit management for campaign reward distribution. Defines specific token rewards that users receive when campaign participation conditions are met.
Reward Configuration:
• Token Association: Link specific token types and amounts to campaigns
• Reward Rules: Define token distribution rules and conditions
• Multi-Token Support: Configure multiple token types per campaign
• Reward Calculation: Set fixed or variable token amounts based on actions
• Distribution Management: Control how and when tokens are distributed to users ### Create campaign token unit (Admin) - [POST /campaigns/{campaignId}/tokens](https://docs.pers.ninja/swagger/campaign-tokens/campaigntokenscontroller_createcampaigntokenunit.md): Add a new token unit to campaign for reward distribution. Admin-only operation. Replaces POST /campaign/admin/{id}/token-units ### Update campaign token unit (Admin) - [PUT /campaigns/{campaignId}/tokens/{tokenUnitId}](https://docs.pers.ninja/swagger/campaign-tokens/campaigntokenscontroller_updatecampaigntokenunit.md): Update an existing token unit in campaign. Admin-only operation. Replaces PUT /campaign/admin/{id}/token-units/{tokenUnitId} ### Remove campaign token unit (Admin) - [DELETE /campaigns/{campaignId}/tokens/{tokenUnitId}](https://docs.pers.ninja/swagger/campaign-tokens/campaigntokenscontroller_removecampaigntokenunit.md): Remove a token unit from campaign. Admin-only operation. Replaces DELETE /campaign/admin/{id}/token-units/{tokenUnitId} ## Campaign Triggers ## Campaign Activation System
Campaign trigger system managing activation rules and eligibility conditions. Defines when and how campaigns activate including complex condition management for sophisticated campaign logic.
Trigger Features:
• Trigger Catalog: Public browsing of available campaign activation triggers
• Condition Management: Create complex trigger conditions with multiple criteria
• Campaign Assignment: Link triggers to campaigns for automated activation
• Eligibility Rules: Define sophisticated user participation requirements
• Event-Based Activation: Trigger campaigns based on user actions and external events ### Get all triggers (Public Catalog) - [GET /campaign-triggers](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_getalltriggers.md): Get all available triggers for campaign configuration. Public access for catalog browsing. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). Replaces GET /campaign/trigger/all ### Create campaign trigger (Admin) - [POST /campaign-triggers](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_createcampaigntrigger.md): Create a new campaign trigger for use in campaigns. Admin-only operation. Replaces POST /campaign/admin/trigger ### Get trigger by ID - [GET /campaign-triggers/{triggerId}](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_gettriggerbyid.md): Get a specific campaign trigger by ID. Useful for dashboard selection and preview. ### Update campaign trigger (Admin) - [PUT /campaign-triggers/{triggerId}](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_updatecampaigntrigger.md): Update an existing campaign trigger. Admin-only operation. Replaces PUT /campaign/admin/trigger/{id} ### Delete campaign trigger (Admin) - [DELETE /campaign-triggers/{triggerId}](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_deletecampaigntrigger.md): Delete an existing campaign trigger. Admin-only operation. Replaces DELETE /campaign/admin/trigger/{id} ### Assign trigger to campaign (Admin) - [PUT /campaign-triggers/{triggerId}/assign/{campaignId}](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_assigntriggertocampaign.md): Assign a trigger to a specific campaign for activation conditions. Admin-only operation. Replaces PUT /campaign/admin/{id}/trigger/{triggerId} ### Remove trigger from campaign (Admin) - [DELETE /campaign-triggers/{triggerId}/assign/{campaignId}](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_removetriggerfromcampaign.md): Remove a trigger assignment from a specific campaign. Admin-only operation. ### Toggle condition in trigger (Admin) - [PUT /campaign-triggers/{triggerId}/conditions](https://docs.pers.ninja/swagger/campaign-triggers/campaigntriggerscontroller_toggleconditionintrigger.md): Add or remove a condition from a trigger (toggle relationship). Admin-only operation. Replaces PUT /campaign/admin/trigger/{triggerId}/condition/{conditionId} ## Campaign Engagements ## Business Relationship Management
B2B engagement management for multi-business campaign relationships. Handles business partnerships and enterprise-level campaign participation in complex loyalty ecosystems.
B2B Features:
• Partner Integration: Manage business-to-business campaign relationships
• Enterprise Programs: Support complex multi-business loyalty initiatives
• Engagement Tracking: Monitor business participation and performance metrics
• Partnership Management: Configure B2B reward sharing and attribution
• Cross-Business Rewards: Enable rewards that span multiple business partners ### Create business engagement for campaign (Admin) - [POST /campaigns/{campaignId}/engagements](https://docs.pers.ninja/swagger/campaign-engagements/campaignengagementscontroller_createbusinessengagementforcampaign.md): Add a business engagement relationship to campaign for business-specific rewards. Admin-only operation. Replaces POST /campaign/admin/{id}/business-engagement ### Update business engagement in campaign (Admin) - [PUT /campaigns/{campaignId}/engagements/{businessEngagementId}](https://docs.pers.ninja/swagger/campaign-engagements/campaignengagementscontroller_updatebusinessengagementincampaign.md): Update an existing business engagement relationship in campaign. Admin-only operation. Replaces PUT /campaign/admin/{id}/business-engagement/{businessEngagementId} ### Remove business engagement from campaign (Admin) - [DELETE /campaigns/{campaignId}/engagements/{businessEngagementId}](https://docs.pers.ninja/swagger/campaign-engagements/campaignengagementscontroller_removebusinessengagementfromcampaign.md): Remove a business engagement relationship from campaign. Admin-only operation. Replaces DELETE /campaign/admin/{id}/business-engagement/{businessEngagementId} ## Campaign Claims ## Reward Claims Processing
Multi-level reward claim processing with comprehensive security features and audit trails. Handles reward distribution with full security features.
Security Features:
• Multi-Level Access: USER, BUSINESS, SYSTEM, ADMIN claim processing levels
• Security Monitoring: IP tracking and behavioral analysis for security
• Audit Tracking: Complete transaction history and activity logs
• Context Attribution: User and business context preservation for tracking
• Claim Verification: Multi-step verification process for high-value rewards
Access Levels:
• USER: Direct customer reward claims with user authentication
• BUSINESS: B2B reward processing with business context attribution
• SYSTEM: Automated claims processing via secure API integration
• ADMIN: Complete administrative oversight and manual claim processing ### Create campaign claim - [POST /campaigns/claims](https://docs.pers.ninja/swagger/campaign-claims/campaignclaimscontroller_createcampaignclaim.md): Process campaign reward claims using role-based detection. Understanding Campaign Claim Flow: 1. WHO can claim (campaign.trigger.triggerType): - CLAIM_BY_USER: End users initiate claims (scan QR, tap NFC, enter geofence) - CLAIM_BY_BUSINESS: Business claims on behalf of users (POS, kiosk) - CLAIM_BY_SYSTEM: Server/webhook automated claims 2. HOW to claim (campaign.triggerSources[].type): - QR_CODE: User scans QR code → App extracts triggerSourceId - NFC_TAG: User taps NFC tag → App reads triggerSourceId - GPS_GEOFENCE: User enters location → App sends lat/lng - API_WEBHOOK: External system triggers via API - TRANSACTION: Purchase event triggers claim Request Body Fields: - triggerSourceId (preferred): The specific trigger source ID from QR/NFC/etc - campaignId (legacy, deprecated): Will be removed Q2 2026 - latitude/longitude: Required for GPS_GEOFENCE or distance-validated claims - userIdentifier: Email/external ID for business/system claims - userInfo: Additional user data if required by campaign - metadata: Custom claim data - multiplier: Reward multiplier (default: 1.0) - context: Dynamic context for ERC721 token personalization (see below) ERC721 Dynamic Context & Template Interpolation: For ERC721 tokens, you can provide a context object whose values become available as {{context.xxx}} placeholders in the token's name/description and AI prompts. Context sources (merge order): 1. TokenMetadata.defaultPromptContext → {{defaults.xxx}} 2. TriggerSource.context (admin QR/NFC) → {{context.xxx}} (always applied) 3. CampaignClaimRequest.context (this field) → {{context.xxx}} (only if allowExternalContextOverwrite=true) Example - Hotel check-in: json { "triggerSourceId": "room-305-qr-uuid", "context": { "guestName": "María García", "roomNumber": "305", "validityEndDate": "2026-04-20T11:00:00Z" } } With TokenMetadata name: "Welcome {{context.guestName}} - Room {{context.roomNumber}}" Result: "Welcome María García - Room 305" App Integration Example: typescript // 1. Get campaign with trigger sources const campaign = await getActiveCampaigns({ include: ['triggerSources'] }); // 2. Determine claim method const triggerTypes = campaign.included?.triggerSources?.map(ts => ts.type); // → ['QR_CODE', 'NFC_TAG'] // 3. Based on type, show appropriate UI and call claim if (triggerTypes.includes('QR_CODE')) { // Open camera, scan QR, extract triggerSourceId claimCampaign({ triggerSourceId: 'scanned-id' }); } ### Get campaign claims with advanced filtering - [GET /campaigns/claims](https://docs.pers.ninja/swagger/campaign-claims/campaignclaimscontroller_getcampaignclaims.md): Get campaign claims with comprehensive filtering options. Use pagination parameters (page & limit) for optimal performance - critical for high-volume campaigns. Legacy support: returns array without params (deprecated - will be removed in future). - campaignId: Filter by specific campaign (optional) - userId: Filter by specific user ID (admin only) - businessId: Filter by specific business ID (admin only) - include: Optionally include related entities (campaign, user, business, transactions) Access Control: - Users: See only their own claims, campaignId optional - Business: See only claims associated with their business account, campaignId optional - Admin: Can filter by any combination of parameters or see all claims Security Notes: - Users cannot access userId or businessId parameters (automatically filtered) - Business accounts automatically filter to their own businessId regardless of parameter - Admin has full access to all filtering options ### Get my campaign claims (Convenience) - [GET /campaigns/claims/me](https://docs.pers.ninja/swagger/campaign-claims/campaignclaimscontroller_getmycampaignclaims.md): Convenience endpoint for authenticated users to retrieve their own campaign claims. Equivalent to GET /campaign-claims but with required authentication and automatic filtering to current user context. Use pagination parameters (page & limit) for optimal performance - recommended for active users. Legacy support: returns array without params (deprecated - will be removed in future). Features: - Automatic user context (no userId parameter needed) - Optional campaign filtering - Requires user authentication - Simplified response structure - Optional entity inclusion (campaign, user, business, transactions) Usage Examples: - GET /campaign-claims/me (all claims for authenticated user) - GET /campaign-claims/me?campaignId=123 (user claims for specific campaign) - GET /campaign-claims/me?include=campaign,transactions (with related entities) ## Redemptions ## Token Exchange System
Token exchange system facilitating conversion between different token types and redemption for rewards. Provides flexible reward experiences through diverse redemption options.
Redemption Features:
• Token Exchange: Convert between different token types with exchange rates
• Reward Catalog: Browse available rewards for token redemption
• Exchange Rules: Configure conversion rates and redemption requirements
• Partner Ecosystem: Redemption options across business partner networks
• Flexible Rewards: Support for products, services, and digital rewards
Redemption Module ### Get redemption by ID - [GET /redemptions/{id}](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_getredemptionbyid.md): Get specific redemption details by ID. Requires valid project API key. ### Update redemption (Admin) - [PUT /redemptions/{id}](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_updateredemption.md): Update existing redemption information. Replaces PUT /redemption/admin/{id} ### Delete redemption (Admin) - [DELETE /redemptions/{id}](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_deleteredemption.md): Permanently delete a redemption. Replaces DELETE /redemption/admin/{id} ### Get redemption available supply - [GET /redemptions/{id}/supply](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_getavailablesupply.md): Get the available supply count for a specific redemption. Used for inventory display. ### Get redemptions (Intelligent Access) - [GET /redemptions](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_getredemptions.md): Intelligent endpoint that adapts based on authentication: Public users get active redemptions only, Admin users get all redemptions with optional filtering. Consolidates GET /redemption and GET /redemption/admin. Use pagination parameters (page & limit) for optimal performance - critical for large datasets. Legacy support: returns array without params (deprecated - will be removed in future). ### Create redemption (Admin) - [POST /redemptions](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_createredemption.md): Create a new redemption with administrative privileges. Replaces POST /redemption/admin ### Toggle redemption status (Admin) - [PUT /redemptions/{id}/status](https://docs.pers.ninja/swagger/redemptions/redemptionscontroller_toggleredemptionstatus.md): Toggle redemption between active and inactive status. Follows standard /status pattern. Replaces PUT /redemption/admin/{id}/toggle-active ## Purchases ## Payment Processing System
Secure payment processing for account balance top-ups through credit card payments. Provides secure financial transactions for premium features and account funding within the loyalty ecosystem.
Payment Features:
• Secure Payments: Credit card processing with industry-standard security
• Balance Top-Up: Add funds to user accounts for premium features
• Payment Methods: Support for multiple payment providers and methods
• Transaction Security: Encrypted payment data and fraud protection
• Account Integration: Seamless integration with token and reward systems
Purchase Module ### Stripe payment webhook (Critical) - [POST /purchases/webhooks/stripe](https://docs.pers.ninja/swagger/purchases/purchasescontroller_handlestripewebhook.md): Handles Stripe payment events for financial reconciliation. CRITICAL: Do not modify without extensive testing. Replaces POST /purchase/stripe-webhook ### Get purchase tokens (Intelligent Access) - [GET /purchases/tokens](https://docs.pers.ninja/swagger/purchases/purchasescontroller_getpurchasetokens.md): Intelligent endpoint that adapts based on authentication. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). Public users get active tokens only, Admin users get filtered tokens. Replaces GET /purchase/token ### Create purchase token (Admin) - [POST /purchases/tokens](https://docs.pers.ninja/swagger/purchases/purchasescontroller_createpurchasetoken.md): Create a new purchase token for the product catalog. Admin-only operation. Replaces POST /purchase/admin/token ### Get donation types - [GET /purchases/donation-types](https://docs.pers.ninja/swagger/purchases/purchasescontroller_getdonationtypes.md): Get all available donation types for public catalog browsing. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). Requires valid project API key. Replaces GET /purchase/donation/type ### Create donation type (Admin) - [POST /purchases/donation-types](https://docs.pers.ninja/swagger/purchases/purchasescontroller_createdonationtype.md): Create a new donation type for system configuration. Admin-only operation. Replaces POST /purchase/admin/donation/type ### Create payment intent (Financial) - [POST /purchases/payment-intents](https://docs.pers.ninja/swagger/purchases/purchasescontroller_createpaymentintent.md): Create a new Stripe payment intent for purchase processing. Requires tenant context for Stripe API key. FINANCIAL OPERATION - handle with care. Replaces POST /purchase/payment-intent ### Update payment intent (Financial) - [PUT /purchases/payment-intents/{paymentIntentId}](https://docs.pers.ninja/swagger/purchases/purchasescontroller_updatepaymentintent.md): Update an existing Stripe payment intent. Requires tenant context for Stripe API key. FINANCIAL OPERATION - handle with care. Replaces PUT /purchase/payment-intent/{paymentIntentId} ### Cancel payment intent (Financial) - [DELETE /purchases/payment-intents/{paymentIntentId}](https://docs.pers.ninja/swagger/purchases/purchasescontroller_cancelpaymentintent.md): Cancel an existing Stripe payment intent. Requires tenant context for Stripe API key. FINANCIAL OPERATION - handle with care. Replaces DELETE /purchase/payment-intent/{paymentIntentId} ### Create user purchase (Financial Transaction) - [POST /purchases](https://docs.pers.ninja/swagger/purchases/purchasescontroller_createuserpurchase.md): Create a new purchase for the authenticated user. BUSINESS CRITICAL - handles real financial transactions with Stripe integration. Requires user and tenant context. Replaces POST /purchase/auth ### Get user purchase history - [GET /purchases/me](https://docs.pers.ninja/swagger/purchases/purchasescontroller_getuserpurchasehistory.md): Get all purchases made by the authenticated user. Use pagination parameters (page & limit) for optimal performance - recommended for users with many purchases. Legacy support: returns array without params (deprecated - will be removed in future). ### Update purchase token (Admin) - [PUT /purchases/tokens/{id}](https://docs.pers.ninja/swagger/purchases/purchasescontroller_updatepurchasetoken.md): Update an existing purchase token in the product catalog. Admin-only operation. Replaces PUT /purchase/admin/token/{id} ### Delete purchase token (Admin) - [DELETE /purchases/tokens/{id}](https://docs.pers.ninja/swagger/purchases/purchasescontroller_deletepurchasetoken.md): Delete an existing purchase token from the product catalog. Admin-only operation. Replaces DELETE /purchase/admin/token/{id} ### Create purchase type (Admin) - [POST /purchases/types](https://docs.pers.ninja/swagger/purchases/purchasescontroller_createpurchasetype.md): Create a new purchase type for system configuration. Admin-only operation. Replaces POST /purchase/admin/type ## Businesses ## Partner Ecosystem Management
Business partner management for multi-stakeholder loyalty programs. Handles partner onboarding, collaboration frameworks, and performance tracking within the reward ecosystem.
Partner Management:
• Partner Onboarding: Register and configure business partners in the ecosystem
• Collaboration Tools: Facilitate joint campaigns and cross-partner rewards
• Performance Analytics: Track partner engagement and contribution metrics
• Incentive Structures: Configure partner-specific reward and commission models
• Community Building: Foster collaborative relationships between ecosystem partners ### Get current business info - [GET /businesses/me](https://docs.pers.ninja/swagger/businesses/businessescontroller_getcurrentbusiness.md): Get business info with current token balances (business authentication required) ### Get all businesses - [GET /businesses](https://docs.pers.ninja/swagger/businesses/businessescontroller_getallbusinesses.md): Get all businesses. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). Project API key users get active businesses only. Admin users (with valid JWT) get full access with query parameters. ### Create a new business - [POST /businesses](https://docs.pers.ninja/swagger/businesses/businessescontroller_createbusiness.md): Create a new business account, will be inactive until activated by admin ### Get business by account address - [GET /businesses/account/{accountAddress}](https://docs.pers.ninja/swagger/businesses/businessescontroller_getbyaccountaddress.md): Get business info by account address ### Get business by ID - [GET /businesses/{id}](https://docs.pers.ninja/swagger/businesses/businessescontroller_getbyid.md): Get business info by ID ### Update a business - [PUT /businesses/{id}](https://docs.pers.ninja/swagger/businesses/businessescontroller_updatebusiness.md): Update a business account ### Create multiple businesses from URL - [POST /businesses/bulk/url](https://docs.pers.ninja/swagger/businesses/businessescontroller_createbusinessesfromurl.md): Create multiple business accounts by fetching a JSON file from the provided URL. The file at the URL is expected to be a JSON object conforming to the BusinessBulkCreateRequestDTO structure, containing an array of business data. ### Toggle business status - [PUT /businesses/{id}/status](https://docs.pers.ninja/swagger/businesses/businessescontroller_togglebusinessstatus.md): Toggle business account active status ### List business members - [GET /businesses/{businessId}/members](https://docs.pers.ninja/swagger/businesses/businessescontroller_getbusinessmembers.md): Get all members of a business. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). Requires BUSINESS auth (min role: VIEWER) or TENANT admin. ### Add member to business - [POST /businesses/{businessId}/members](https://docs.pers.ninja/swagger/businesses/businessescontroller_addbusinessmember.md): Add a user as a member of the business. Requires BUSINESS auth (min role: ADMIN) or TENANT admin. ### Update member role - [PUT /businesses/{businessId}/members/{userId}](https://docs.pers.ninja/swagger/businesses/businessescontroller_updatememberrole.md): Update the role of an existing business member. Requires BUSINESS auth (min role: ADMIN) or TENANT admin. ### Remove member from business - [DELETE /businesses/{businessId}/members/{userId}](https://docs.pers.ninja/swagger/businesses/businessescontroller_removebusinessmember.md): Remove a user from business membership. Requires BUSINESS auth (min role: ADMIN) or TENANT admin. ## Transactions ## Transaction Management System
Comprehensive transaction management for credits and tokens with secure processing and real-time balance updates. Handles all operations within the loyalty platform.
Transaction Operations:
• Token Minting: Create new tokens and add to user accounts
• Token Transfers: Secure peer-to-peer token transfers between users
• Token Burning: Remove tokens from circulation with proper audit trails
• Balance Queries: Real-time balance checks across multiple token types
• Transaction Authorization: Verify user permissions and sufficient balances
• Transaction History: Complete audit logs for all operations ### Get current user/business transactions - [GET /transactions/me](https://docs.pers.ninja/swagger/transactions/transactionscontroller_getcurrentusertransactions.md): Consolidated endpoint for user/business transactions. Use role parameter to filter: SENDER (sent), RECIPIENT (received), or omit for all transactions. Use include parameter to enrich with full entity data. Always returns PaginatedResponseDTO. ### Get all transactions with advanced filtering - [GET /transactions](https://docs.pers.ninja/swagger/transactions/transactionscontroller_getalltransactions.md): Get transactions with comprehensive filtering options: - include: Enrich with full entity data (sender, recipient, business) - search: Wildcard search for ID, address or transaction hash - participantId: Filter by user/business/tenant ID - role: Filter by SENDER, RECIPIENT, or both (omit for all) - status: Filter by transaction status - tokenType: Filter by token type - type: Filter by transaction type (MINT, BURN, TRANSFER) - Always returns PaginatedResponseDTO ### Create transaction - [POST /transactions](https://docs.pers.ninja/swagger/transactions/transactionscontroller_createsystemtransaction.md): Create any type of transaction (MINT/TRANSFER/BURN) using role-based trigger detection. Sender: Determined from authentication context or provided explicitly. ERC721 MINT with Dynamic Context: For ERC721 mints, you can provide a context object for template interpolation and AI prompts. Values become available as {{context.xxx}} placeholders in TokenMetadata name/description. Example: json { "web3TransactionType": "MINT", "recipient": { "accountId": "user-uuid", "accountType": "USER" }, "token": { "tokenEntityId": "token-uuid" }, "amount": 1, "context": { "awardReason": "Employee of the Month", "recipientName": "John Smith" } } Depending on transaction type and signing context, returns prepared transaction for client-side signing or executes server-side directly. ### Get transaction by ID - [GET /transactions/{id}](https://docs.pers.ninja/swagger/transactions/transactionscontroller_gettransactionbyid.md): Get single transaction by ID with optional entity inclusion. Use include parameter to enrich with full entity data. Requires valid project API key. ### Prepare existing transaction for client-side signing - [GET /transactions/{id}/prepare](https://docs.pers.ninja/swagger/transactions/transactionscontroller_preparetransactionbyid.md): Prepares transaction data for client-side execution from existing transaction ID. Returns the data needed for the client to sign and submit the transaction. ### Sign transaction and return signature only (no submission) - [POST /transactions/{id}/sign](https://docs.pers.ninja/swagger/transactions/transactionscontroller_signtransactiononly.md): Signs a custodial EIP-712 transaction and returns the signature without submitting to the blockchain. Use this for business interface flows where the signature is displayed/scanned and submitted separately. ### Submit client-side signed transaction - [POST /transactions/submit](https://docs.pers.ninja/swagger/transactions/transactionscontroller_submittransaction.md): Submits a signed transaction from the client. This method is used to finalize the transaction after the client has signed it. ### Export all transactions as CSV - [GET /transactions/export/csv](https://docs.pers.ninja/swagger/transactions/transactionscontroller_exporttransactionsascsv.md): Downloads all transactions as a CSV file. RLS ensures tenant isolation automatically. File includes all transaction data formatted for business analysis. ## Users ## User Account Management
User account management and profile operations for loyalty platform participants. Handles user registration, authentication, profile management, and account lifecycle.
User Operations:
• Account Registration: User signup and profile creation with verification
• Authentication: Secure login and session management
• Profile Management: User profile updates and preference configuration
• Account Security: Password management and two-factor authentication
• Privacy Controls: Data management and privacy settings for users ### Get current user info - [GET /users/me](https://docs.pers.ninja/swagger/users/userscontroller_getcurrentuser.md): Get authenticated user account info. Use include=status,balances to include related data. Note: Including status/balances adds latency - consider separate calls for performance-critical scenarios. Wallets include virtual counterfactual addresses for chains with active tokens. ### Update current user - [PUT /users/me](https://docs.pers.ninja/swagger/users/userscontroller_updatecurrentuser.md): Update authenticated user account ### Get current user status - [GET /users/me/status](https://docs.pers.ninja/swagger/users/userscontroller_getcurrentuserstatus.md): Get authenticated user status types. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). ### Check if user exists - [GET /users/exists](https://docs.pers.ninja/swagger/users/userscontroller_checkuserexists.md): Check if a user exists using any identifier field (id, email, etc.) ### Get all public profiles - [GET /users/public](https://docs.pers.ninja/swagger/users/userscontroller_getallpublicprofiles.md): Get all public user profiles. Use pagination parameters (page & limit) for optimal performance - essential for large user bases. Legacy support: returns array without params (deprecated - will be removed in future). ### Get public profile - [GET /users/public/{id}](https://docs.pers.ninja/swagger/users/userscontroller_getpublicprofile.md): Get a public profile by user ID ### Get all user status types - [GET /users/status-types](https://docs.pers.ninja/swagger/users/userscontroller_getalluserstatustypes.md): Get all available user status types. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). ### Create user status type - [POST /users/status-types](https://docs.pers.ninja/swagger/users/userscontroller_createuserstatustype.md): Create user status type as admin ### Get user status type - [GET /users/status-types/{id}](https://docs.pers.ninja/swagger/users/userscontroller_getuserstatustype.md): Get a user status type by ID ### Update user status type - [PUT /users/status-types/{id}](https://docs.pers.ninja/swagger/users/userscontroller_updateuserstatustype.md): Update user status type as admin ### Delete user status type - [DELETE /users/status-types/{id}](https://docs.pers.ninja/swagger/users/userscontroller_deleteuserstatustype.md): Delete user status type as admin ### Update eligible token for status type - [PUT /users/status-types/{id}/eligible-tokens/{tokenAddress}](https://docs.pers.ninja/swagger/users/userscontroller_updateuserstatustypeeligibletoken.md): Add or remove eligible token for user status type as admin ### Get user info - [POST /users/info](https://docs.pers.ninja/swagger/users/userscontroller_getuserinfo.md): Get user account info (business with user management permission OR admin authentication required). Use include parameter for related data. Note: Including status/balances adds latency - consider separate calls for performance-critical scenarios. ### Get user balance - [POST /users/balance](https://docs.pers.ninja/swagger/users/userscontroller_getuserbalance.md): Get user account with current token balances (business with user management permission OR admin authentication required) ### Create or update user account - [POST /users](https://docs.pers.ninja/swagger/users/userscontroller_createorupdateuser.md): Create or update user account(s). Supports single user (business/admin) or bulk operations (admin only) ### Get all users - [GET /users](https://docs.pers.ninja/swagger/users/userscontroller_getallusers.md): Get all users with role-based access. Use pagination parameters (page & limit) for optimal performance. With merge param, only checks duplicates for users on current page (smart merge). Project API key users get public profiles only. Admin users get full access. ### Get user by identifier - [GET /users/{identifier}](https://docs.pers.ninja/swagger/users/userscontroller_getuserbyidentifier.md): Get user by any unique identifier field (id, email, externalId, accountAddress, etc.). Admin only. Use include parameter for related data. Note: Including status/balances adds latency - consider separate calls for performance-critical scenarios. ### Update user by identifier (admin) - [PUT /users/{identifier}](https://docs.pers.ninja/swagger/users/userscontroller_updateuserbyidentifier.md): Update user account by any unique identifier field (id, email, externalId, accountAddress, etc.). Admin only. ### Delete user by identifier (admin) - [DELETE /users/{identifier}](https://docs.pers.ninja/swagger/users/userscontroller_deleteuserbyidentifier.md): Soft delete user by any unique identifier field (id, email, externalId, accountAddress, etc.). Admin only. ⚠️ This operation is irreversible via API - consider using PUT /users/{identifier}/status for temporary deactivation. ### Create users from URL (admin) - [POST /users/bulk/url](https://docs.pers.ninja/swagger/users/userscontroller_createusersfromurl.md): Create user accounts from external URL as admin ### Set or toggle user status by identifier - [PUT /users/{identifier}/status](https://docs.pers.ninja/swagger/users/userscontroller_toggleuserstatusbyidentifier.md): Set or toggle user active status by any unique identifier field (id, email, externalId, accountAddress, etc.). If body contains { isActive: true/false }, sets explicitly. If no body, toggles. Admin only. ### Restore deleted user (admin) - [POST /users/{identifier}/restore](https://docs.pers.ninja/swagger/users/userscontroller_restoreuserbyidentifier.md): Restore a soft-deleted user within the 30-day grace period. After GDPR anonymization, restoration is not possible. ### Get current user balance (deprecated) - [GET /users/me/balance](https://docs.pers.ninja/swagger/users/userscontroller_getcurrentuserbalance.md): Get authenticated user account with current token balances ## Balances ## Account Balance Management
Real-time balance tracking and management across all token types and user accounts. Provides comprehensive balance queries and balance-related operations.
Balance Features:
• Multi-Token Balances: Track balances across different token types per user
• Real-Time Updates: Instant balance updates from all transaction sources
• Balance History: Historical balance tracking and change audit trails
• Balance Queries: Flexible balance lookup with filtering and aggregation
• Balance Notifications: Alert systems for balance changes and thresholds ### Get account balance by address (Admin) - [GET /balances/accounts/{accountAddress}](https://docs.pers.ninja/swagger/balances/balancescontroller_getaccountbalance.md): Get detailed balance information including token metadata for any account address. Requires tenant admin privileges. Replaces GET /balance/admin/account/{accountAddress} ## Files ## File Management System
File upload and management system for platform assets including campaign images, user avatars, and document attachments with secure storage and access control.
File Operations:
• Secure Upload: File upload with type validation and security scanning
• Asset Management: Organize and manage platform media assets
• Access Control: Role-based file access and sharing permissions
• CDN Integration: Fast global file delivery through content delivery networks
• File Processing: Automatic image resizing and format optimization ### Generate signed URL for entity storage - [POST /files/entity-storage-url](https://docs.pers.ninja/swagger/files/filescontroller_getentitystorageurl.md): Creates S3 signed URLs for uploading or downloading entity files. Supports both business and admin authentication flows. ## Web3 Chains ## Blockchain Network Management
Blockchain network configuration and management for multi-chain token operations. Handles network connections, chain switching, and blockchain-specific operations.
Chain Operations:
• Multi-Chain Support: Connect to multiple blockchain networks simultaneously
• Network Configuration: Configure blockchain endpoints and network parameters
• Chain Switching: Dynamic switching between different blockchain networks
• Network Status: Real-time monitoring of blockchain network health and status
• Gas Management: Optimize transaction costs across different networks ### Get Web3 chain data by chain ID - [GET /chains/{chainId}](https://docs.pers.ninja/swagger/web3-chains/web3chainscontroller_getchaindata.md): Retrieve comprehensive chain data including authentication JWT token valid for 30 days. Supports both mainnet and testnet chains. ## Contracts ## Smart Contract Management
Smart contract deployment and interaction management for blockchain-based loyalty operations. Handles contract lifecycle and blockchain integration.
Contract Operations:
• Contract Deployment: Deploy loyalty-related smart contracts to blockchain networks
• Contract Interaction: Execute smart contract functions for token operations
• Contract Monitoring: Track contract events and transaction confirmations
• Contract Upgrades: Manage contract versioning and upgrade procedures
• Multi-Chain Contracts: Deploy and manage contracts across multiple blockchains ### Create a new Web3 contract (Admin) - [POST /contracts](https://docs.pers.ninja/swagger/contracts/web3contractscontroller_createcontract.md): Create a new Web3 contract with administrative privileges. Requires tenant admin access. Replaces POST /contract ## Auth ## Authentication & Authorization
Comprehensive authentication and authorization system supporting multiple access levels including users, businesses, admins, and system-level access with JWT-based security.
Auth Features:
• Multi-Level Access: Support for USER, BUSINESS, ADMIN, SYSTEM authentication levels
• JWT Security: JSON Web Token-based authentication with secure key management
• Role-Based Access: Fine-grained permission system with role hierarchy
• API Key Management: Secure API key generation and validation for system integrations
• Session Management: Secure session handling with automatic expiration and refresh ### Create authentication token - [POST /auth/token](https://docs.pers.ninja/swagger/auth/authcontroller_createtoken.md): Universal token creation with consistent token-in-body pattern. ## Authentication Flows ### USER AUTHENTICATION - Header: x-project-key (tenant identification) - Body: { authToken: "jwt_from_provider", authType: "user" } - Returns: User session with PERS JWT tokens ### BUSINESS AUTHENTICATION - Header: x-project-key (tenant identification) - Body: { authToken: "jwt_from_provider", authType: "business", context: { businessId: "uuid" } } - Returns: Business session with PERS JWT tokens (includes role in JWT) - If user has single business membership, context.businessId is auto-selected - If user has multiple memberships without context.businessId, returns MULTIPLE_CONTEXT_SELECTION_REQUIRED error with available options ### ADMIN AUTHENTICATION - Header: x-project-key (tenant identification) - Body: { authToken: "firebase_jwt", authType: "tenant" } - Returns: Admin session with PERS JWT tokens --- ## Third-Party JWT Requirements When providing authToken from an external identity provider, the JWT must meet these requirements: ### JWT Header | Field | Required | Description | |-------|----------|-------------| | kid | Yes | Key ID matching a key in your JWKS | | alg | Yes | Signing algorithm (RS256, ES256, EdDSA) | ### JWT Payload Claims | Claim | Required | Description | |-------|----------|-------------| | iss | Yes | Issuer URL (used for JWKS discovery) | | sub | Yes | Subject identifier (user ID) | | aud | Yes | Audience (your registered client ID) | | exp | Yes | Expiration timestamp (Unix epoch) | | iat | Yes | Issued at timestamp (Unix epoch) | ### Provider Requirements Your identity provider must expose public keys via one of: 1. {issuer}/.well-known/jwks.json (JWKS endpoint) 2. {issuer}/.well-known/openid-configuration (OIDC discovery with jwks_uri) ### Verification Flow 1. PERS extracts iss claim from JWT 2. Fetches JWKS from {issuer}/.well-known/jwks.json 3. Matches kid header to find signing public key 4. Verifies signature using matched key 5. Validates exp, iat, aud claims 6. Issues PERS access/refresh tokens on success ### PERS JWKS (For verifying our tokens) - JWKS: https://api.pers.ninja/.well-known/jwks.json - Discovery: https://api.pers.ninja/.well-known/openid-configuration ### Refresh authentication tokens - [POST /auth/refresh](https://docs.pers.ninja/swagger/auth/authcontroller_refresh.md): Refresh access tokens using valid refresh token ### Verify JWT token - [POST /auth/verify](https://docs.pers.ninja/swagger/auth/authcontroller_verifytoken.md): Verify JWT tokens with automatic issuer detection: - Decodes JWT to extract issuer claim - PERS tokens: Verified internally - External tokens: Future support planned - Standards-compliant JWT verification ## Root ## Platform Infrastructure
Core platform infrastructure endpoints including health checks, system status, and platform configuration. Provides essential system-level operations and monitoring.
Infrastructure Operations:
• Health Monitoring: System health checks and status reporting
• Platform Status: Real-time platform operational status
• Configuration Access: System configuration and environment information
• Diagnostic Tools: Platform diagnostics and troubleshooting endpoints
• System Integration: Core infrastructure for system-level operations ### RootController_get - [GET /](https://docs.pers.ninja/swagger/root/rootcontroller_get.md) ### RootController_getCurrentTime - [GET /healthcheck](https://docs.pers.ninja/swagger/root/rootcontroller_getcurrenttime.md) ### Check if tenant system api key is valid - [GET /system](https://docs.pers.ninja/swagger/root/rootcontroller_getsystem.md): Check if tenant system api key is valid ### ADMIN: Check if admin - [GET /admin](https://docs.pers.ninja/swagger/root/rootcontroller_getadmin.md): Get if admin ### RootController_testGeo - [GET /geolocation](https://docs.pers.ninja/swagger/root/rootcontroller_testgeo.md) ## Well-known ## Security Infrastructure
JSON Web Key Set (JWKS) endpoints for JWT token verification. Provides public keys for secure authentication token validation across the platform ecosystem.
Security Features:
• JWKS Endpoints: Standard JSON Web Key Set for JWT verification
• Public Key Distribution: Secure distribution of verification keys
• Token Validation: Enable third-party JWT token verification
• Security Standards: Compliance with OAuth 2.0 and OpenID Connect
• Cross-Platform Auth: Support for distributed authentication verification ### Get JSON Web Key Set (JWKS) - [GET /jwks.json](https://docs.pers.ninja/swagger/well-known/jwkscontroller_getjwks.md) ### Get OIDC Discovery Document - [GET /openid-configuration](https://docs.pers.ninja/swagger/well-known/jwkscontroller_getopenidconfiguration.md) ## Trigger Sources ### Create trigger source - [POST /trigger-sources](https://docs.pers.ninja/swagger/trigger-sources/triggersourcescontroller_createtriggersource.md): Create a new trigger source (QR code, NFC tag, webhook, geofence, etc.) for a campaign ### Get all trigger sources - [GET /trigger-sources](https://docs.pers.ninja/swagger/trigger-sources/triggersourcescontroller_getalltriggersources.md): Retrieve all trigger sources with optional filtering and pagination. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). ### Get trigger source by ID - [GET /trigger-sources/{id}](https://docs.pers.ninja/swagger/trigger-sources/triggersourcescontroller_gettriggersource.md): Retrieve a specific trigger source with its configuration ### Update trigger source - [PUT /trigger-sources/{id}](https://docs.pers.ninja/swagger/trigger-sources/triggersourcescontroller_updatetriggersource.md): Update an existing trigger source configuration ### Delete trigger source - [DELETE /trigger-sources/{id}](https://docs.pers.ninja/swagger/trigger-sources/triggersourcescontroller_deletetriggersource.md): Soft delete a trigger source (sets deletedAt timestamp) ## Business Types ### Create a new business type - [POST /businesses/types](https://docs.pers.ninja/swagger/business-types/businesstypescontroller_createbusinesstype.md): Create a new business type ### Update a business type - [PUT /businesses/types](https://docs.pers.ninja/swagger/business-types/businesstypescontroller_updatebusinesstype.md): Update a business type ### Get all business types - [GET /businesses/types](https://docs.pers.ninja/swagger/business-types/businesstypescontroller_getallbusinesstypes.md): Get all business types. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). ### Delete a business type - [DELETE /businesses/types/{id}](https://docs.pers.ninja/swagger/business-types/businesstypescontroller_deletebusinesstype.md): Delete a business type ## Redemption Types ### Get redemption types - [GET /redemptions/types](https://docs.pers.ninja/swagger/redemption-types/redemptiontypescontroller_getredemptiontypes.md): Get all available redemption types for client reference. Requires valid project API key. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). ### Create redemption type (Admin) - [POST /redemptions/types](https://docs.pers.ninja/swagger/redemption-types/redemptiontypescontroller_createredemptiontype.md): Create a new redemption type for system configuration. Replaces POST /redemption/admin/type ## Redemption Redeems ### Execute redemption (Unified) - [POST /redemptions/redeems](https://docs.pers.ninja/swagger/redemption-redeems/redemptionredeemscontroller_executeredemption.md): Process redemption execution using role-based detection. Supports user, business, and admin redemption processing. ERC721 Dynamic Context & Template Interpolation: For ERC721 tokens, you can provide a context object whose values become available as {{context.xxx}} placeholders in the token's name/description and AI prompts. Context sources (merge order): 1. TokenMetadata.defaultPromptContext → {{defaults.xxx}} 2. Redemption.context (admin-defined) → {{context.xxx}} (always applied) 3. RedemptionRedeemRequest.context (this field) → {{context.xxx}} (only if allowExternalContextOverwrite=true) Example - Event ticket redemption: json { "redemptionId": "redemption-uuid", "context": { "seatNumber": "A12", "attendeeName": "John Smith" } } With TokenMetadata name: "{{context.attendeeName}} - Seat {{context.seatNumber}}" Result: "John Smith - Seat A12" ### Get redemption redeems with advanced filtering - [GET /redemptions/redeems](https://docs.pers.ninja/swagger/redemption-redeems/redemptionredeemscontroller_getredemptionredeems.md): Get redemption redeems with comprehensive filtering options: - redemptionId: Filter by specific redemption (optional) - userId: Filter by specific user ID (admin only) - businessId: Filter by specific business ID (admin only) - include: Optionally include related entities (redemption, user, business, transactions) Access Control: - Users: See only their own redemptions - Business: See only redemptions associated with their business account - Admin: Can filter by any combination of parameters or see all redemptions Security Notes: - Users cannot access userId or businessId parameters (automatically filtered) - Business accounts automatically filter to their own businessId regardless of parameter - Admin has full access to all filtering options Use pagination parameters (page & limit) for optimal performance - critical for high-volume data. Legacy support: returns array without params (deprecated - will be removed in future). ### Get my redemption redeems (Convenience) - [GET /redemptions/redeems/me](https://docs.pers.ninja/swagger/redemption-redeems/redemptionredeemscontroller_getmyredemptionredeems.md): Convenience endpoint for authenticated users to retrieve their own redemption redeems. Equivalent to GET /redemption-redeems but with required authentication and automatic filtering to current user context. Features: - Automatic user context (no userId parameter needed) - Optional redemption filtering - Optional status filtering (PENDING, PROCESSING, COMPLETED, FAILED) - Requires user authentication - Simplified response structure - Optional entity inclusion (redemption, user, business, transactions) - Use pagination parameters (page & limit) for optimal performance - recommended for active users - Legacy support: returns array without params (deprecated - will be removed in future) Usage Examples: - GET /redemption-redeems/me (all redemptions for authenticated user) - GET /redemption-redeems/me?redemptionId=123 (specific user redemption) - GET /redemption-redeems/me?status=COMPLETED (only completed redemptions) - GET /redemption-redeems/me?page=1&limit=10 (paginated results) - GET /redemption-redeems/me?include=redemption,user (with related entities) - GET /redemption-redeems/me?include=redemption,transactions (with transactions) ### Get specific redemption redeem - [GET /redemptions/redeems/{redeemId}](https://docs.pers.ninja/swagger/redemption-redeems/redemptionredeemscontroller_getredemptionredeembyid.md): Get current status of a specific redemption redeem with automatic access control based on authentication context. Optionally include related entities (redemption, user, business, transactions). ## Redemption Tokens ### Add token unit to redemption (Admin) - [POST /redemptions/{redemptionId}/tokens](https://docs.pers.ninja/swagger/redemption-tokens/redemptiontokenscontroller_addtokenunittoredemption.md): Add a new token unit to an existing redemption. Replaces POST /redemption/admin/{id}/token-units ### Update redemption token unit (Admin) - [PUT /redemptions/{redemptionId}/tokens/{tokenUnitId}](https://docs.pers.ninja/swagger/redemption-tokens/redemptiontokenscontroller_updatetokenunit.md): Update an existing token unit within a redemption. Replaces PUT /redemption/admin/{id}/token-units/{tokenUnitId} ### Remove token unit from redemption (Admin) - [DELETE /redemptions/{redemptionId}/tokens/{tokenUnitId}](https://docs.pers.ninja/swagger/redemption-tokens/redemptiontokenscontroller_removetokenunit.md): Remove an existing token unit from a redemption. Replaces DELETE /redemption/admin/{id}/token-units/{tokenUnitId} ## API Keys ### Get all tenant API keys (Admin) - [GET /api-keys](https://docs.pers.ninja/swagger/api-keys/apikeyscontroller_gettenantapikeys.md): Retrieve all valid API keys for the current tenant. Admin-only operation that returns keys based on tenant context from authentication. Supports optional filtering by API key type. Use pagination parameters (page & limit) for optimal performance. Legacy support: returns array without params (deprecated - will be removed in future). ### Create new JWT token (Admin) - [POST /api-keys](https://docs.pers.ninja/swagger/api-keys/apikeyscontroller_createapikey.md): Create a new JWT token for the tenant. Store this token securely - it cannot be retrieved again. JWT tokens are a specialized type of API key for authentication purposes. ### Revoke API key (Admin) - [DELETE /api-keys/{id}](https://docs.pers.ninja/swagger/api-keys/apikeyscontroller_revokeapikey.md): Permanently revoke an API key. This operation cannot be undone. The key will be marked as revoked and will no longer be valid for authentication. ## Webhooks ### Create webhook - [POST /hooks](https://docs.pers.ninja/swagger/webhooks/webhookcontroller_create.md) ### List webhooks - [GET /hooks](https://docs.pers.ninja/swagger/webhooks/webhookcontroller_list.md) ### Get webhook executions - [GET /hooks/executions](https://docs.pers.ninja/swagger/webhooks/webhookcontroller_getexecutions.md): Get webhook execution history with filtering options. Filters: - hookId: Filter by specific webhook (optional - omit for all webhooks) - status: Filter by execution status (success, failed, pending) - dateFrom: Filter executions after this date (ISO 8601) - dateTo: Filter executions before this date (ISO 8601) Use pagination parameters (page & limit) for optimal performance. ### Get webhook - [GET /hooks/{hookId}](https://docs.pers.ninja/swagger/webhooks/webhookcontroller_get.md) ### Update webhook - [PUT /hooks/{hookId}](https://docs.pers.ninja/swagger/webhooks/webhookcontroller_update.md) ### Delete webhook - [DELETE /hooks/{hookId}](https://docs.pers.ninja/swagger/webhooks/webhookcontroller_delete.md) ## Webhook Proxy ### Receive callback from external system - [POST /hooks/{projectKey}/executions/{executionId}/callback](https://docs.pers.ninja/swagger/webhook-proxy/webhookproxycontroller_processcallback.md): Receive workflow completion callback from external systems (e.g., n8n). URL format: /hooks/{projectKey}/executions/{executionId}/callback Security: - Project key identifies tenant (RLS enforces isolation) - Execution ID is UUIDv4 (unguessable) - Execution must be < 1 hour old - Execution cannot receive multiple callbacks No authentication required - security via execution ID secrecy + RLS. ### Trigger webhook (forward request to configured target) - [GET /hooks/{projectKey}/{hookId}](https://docs.pers.ninja/swagger/webhook-proxy/webhookproxycontroller_receivewebhook_get.md): Project key in URL path identifies the tenant. Configure webhook URL as: /hooks/{projectKey}/{hookId}. Returns wrapped response with execution metadata. ### Trigger webhook (forward request to configured target) - [POST /hooks/{projectKey}/{hookId}](https://docs.pers.ninja/swagger/webhook-proxy/webhookproxycontroller_receivewebhook_post.md): Project key in URL path identifies the tenant. Configure webhook URL as: /hooks/{projectKey}/{hookId}. Returns wrapped response with execution metadata. ### Trigger webhook (forward request to configured target) - [PUT /hooks/{projectKey}/{hookId}](https://docs.pers.ninja/swagger/webhook-proxy/webhookproxycontroller_receivewebhook_put.md): Project key in URL path identifies the tenant. Configure webhook URL as: /hooks/{projectKey}/{hookId}. Returns wrapped response with execution metadata. ### Trigger webhook (forward request to configured target) - [DELETE /hooks/{projectKey}/{hookId}](https://docs.pers.ninja/swagger/webhook-proxy/webhookproxycontroller_receivewebhook_delete.md): Project key in URL path identifies the tenant. Configure webhook URL as: /hooks/{projectKey}/{hookId}. Returns wrapped response with execution metadata. ### Trigger webhook (forward request to configured target) - [PATCH /hooks/{projectKey}/{hookId}](https://docs.pers.ninja/swagger/webhook-proxy/webhookproxycontroller_receivewebhook_patch.md): Project key in URL path identifies the tenant. Configure webhook URL as: /hooks/{projectKey}/{hookId}. Returns wrapped response with execution metadata. ### Trigger webhook (forward request to configured target) - [OPTIONS /hooks/{projectKey}/{hookId}](https://docs.pers.ninja/swagger/webhook-proxy/webhookproxycontroller_receivewebhook_options.md): Project key in URL path identifies the tenant. Configure webhook URL as: /hooks/{projectKey}/{hookId}. Returns wrapped response with execution metadata. ### Trigger webhook (forward request to configured target) - [HEAD /hooks/{projectKey}/{hookId}](https://docs.pers.ninja/swagger/webhook-proxy/webhookproxycontroller_receivewebhook_head.md): Project key in URL path identifies the tenant. Configure webhook URL as: /hooks/{projectKey}/{hookId}. Returns wrapped response with execution metadata.