Skip to content

PERS-api docs (2.0.2)

Download OpenAPI description
swagger.json
swagger.yaml
Overview
Languages
Servers
Mock server

https://docs.pers.ninja/_mock/swagger/

https://api.pers.ninja/v2/

Tenants

Operations

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

Request

Create a new tenant (project) in the system. This is the initial setup step for new organizations.

Security
projectKey and businessApiKey
Bodyapplication/jsonrequired
projectNamestringrequired
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/tenants \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-project-key: YOUR_API_KEY_HERE' \
  -d '{
    "projectName": "string"
  }'

Responses

Tenant created successfully

Bodyapplication/json
projectNamestringrequired

Name of the tenant.

acronymstringrequired

Acronym of the tenant.

idstringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

createdAtstring(date-time)required

Date when tenant was created.

projectDescriptionstring

Description of the tenant.

projectWebsitestring

Website of the tenant.

projectEmailstring

Email of the tenant.

projectImageUrlstring

Image URL of the tenant.

projectApiKeystringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

testnetProjectApiKeystringrequired

Testnet project API key for tenant. Used in case of testnet project.

stripeApiKeystring

Stripe API key for tenant. Used in case of stripe payment.

stripeWebhookSecretstring

Stripe webhook secret for tenant. Used in case of stripe payment.

loginTokenstring

This is an optional field for any extra login requirements for your users.

allowJWTForUnauthenticatedUsersbooleanrequired

This is an optional field for any extra login requirements for your users.

firebaseTenantIdstring
jwtstring

JWT token for tenant admin user. This token is used to authenticate tenant admin user. It is generated when tenant is created. Please store it securely, you will not be able to see this again. However, you can generate a new one if needed.

apiPrivateKeystring

API private key for tenant. This key is used to authenticate tenant when making API requests. It is generated on demand. Please store it securely, you will not be able to see this again. However, you can generate a new one if needed.

defaultWalletManagementTypestringrequired

Default wallet management type for tenant. This is used when creating a new wallet for the tenant. It can be either CUSTODIAL or NON_CUSTODIAL. CUSTODIAL means that the wallet is managed by the platform, while NON_CUSTODIAL means that the wallet is managed by the user.

Default "custodial"
Enum"custodial""non-custodial"
Response
application/json
{
  "projectName": "string",
  "acronym": "string",
  "id": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "projectDescription": "string",
  "projectWebsite": "string",
  "projectEmail": "string",
  "projectImageUrl": "string",
  "projectApiKey": "string",
  "testnetProjectApiKey": "string",
  "stripeApiKey": "string",
  "stripeWebhookSecret": "string",
  "loginToken": "string",
  "allowJWTForUnauthenticatedUsers": true,
  "firebaseTenantId": "string",
  "jwt": "string",
  "apiPrivateKey": "string",
  "defaultWalletManagementType": "custodial"
}

Update tenant configuration

Request

ADMIN: Update tenant information and settings

Security
tenantAdminJWT
Bodyapplication/jsonrequired
projectNamestring

The project name

Example: "My Project"
projectDescriptionstring

The project description

stripeApiKeystring
stripeWebhookSecretstring
stripePublishableKeystring
loginTokenstring
allowJWTForUnauthenticatedUsersboolean

This is an optional field for any extra login requirements for your users.

firebaseTenantIdstring
projectWebsitestring
projectEmailstring
projectImageUrlstring
curl -i -X PUT \
  https://docs.pers.ninja/_mock/swagger/tenants \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "projectName": "My Project",
    "projectDescription": "string",
    "stripeApiKey": "string",
    "stripeWebhookSecret": "string",
    "stripePublishableKey": "string",
    "loginToken": "string",
    "allowJWTForUnauthenticatedUsers": true,
    "firebaseTenantId": "string",
    "projectWebsite": "string",
    "projectEmail": "string",
    "projectImageUrl": "string"
  }'

Responses

Tenant updated successfully

Bodyapplication/json
projectNamestringrequired

Name of the tenant.

acronymstringrequired

Acronym of the tenant.

idstringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

createdAtstring(date-time)required

Date when tenant was created.

projectDescriptionstring

Description of the tenant.

projectWebsitestring

Website of the tenant.

projectEmailstring

Email of the tenant.

projectImageUrlstring

Image URL of the tenant.

projectApiKeystringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

testnetProjectApiKeystringrequired

Testnet project API key for tenant. Used in case of testnet project.

stripeApiKeystring

Stripe API key for tenant. Used in case of stripe payment.

stripeWebhookSecretstring

Stripe webhook secret for tenant. Used in case of stripe payment.

loginTokenstring

This is an optional field for any extra login requirements for your users.

allowJWTForUnauthenticatedUsersbooleanrequired

This is an optional field for any extra login requirements for your users.

firebaseTenantIdstring
jwtstring

JWT token for tenant admin user. This token is used to authenticate tenant admin user. It is generated when tenant is created. Please store it securely, you will not be able to see this again. However, you can generate a new one if needed.

apiPrivateKeystring

API private key for tenant. This key is used to authenticate tenant when making API requests. It is generated on demand. Please store it securely, you will not be able to see this again. However, you can generate a new one if needed.

defaultWalletManagementTypestringrequired

Default wallet management type for tenant. This is used when creating a new wallet for the tenant. It can be either CUSTODIAL or NON_CUSTODIAL. CUSTODIAL means that the wallet is managed by the platform, while NON_CUSTODIAL means that the wallet is managed by the user.

Default "custodial"
Enum"custodial""non-custodial"
Response
application/json
{
  "projectName": "string",
  "acronym": "string",
  "id": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "projectDescription": "string",
  "projectWebsite": "string",
  "projectEmail": "string",
  "projectImageUrl": "string",
  "projectApiKey": "string",
  "testnetProjectApiKey": "string",
  "stripeApiKey": "string",
  "stripeWebhookSecret": "string",
  "loginToken": "string",
  "allowJWTForUnauthenticatedUsers": true,
  "firebaseTenantId": "string",
  "jwt": "string",
  "apiPrivateKey": "string",
  "defaultWalletManagementType": "custodial"
}

Get public tenant information

Request

Retrieve public tenant information visible to all users

Security
projectKey
curl -i -X GET \
  https://docs.pers.ninja/_mock/swagger/tenants/public \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Public tenant information retrieved successfully

Bodyapplication/json
projectNamestringrequired

Name of the tenant.

acronymstringrequired

Acronym of the tenant.

idstringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

createdAtstring(date-time)required

Date when tenant was created.

projectDescriptionstring

Description of the tenant.

projectWebsitestring

Website of the tenant.

projectEmailstring

Email of the tenant.

projectImageUrlstring

Image URL of the tenant.

Response
application/json
{
  "projectName": "string",
  "acronym": "string",
  "id": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "projectDescription": "string",
  "projectWebsite": "string",
  "projectEmail": "string",
  "projectImageUrl": "string"
}

Get client configuration

Request

Retrieve client-side configuration for the project

Security
projectKey
curl -i -X GET \
  https://docs.pers.ninja/_mock/swagger/tenants/client-config \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Client configuration retrieved successfully

Bodyapplication/json
projectNamestringrequired

The project name

Example: "My Project"
idstringrequired

The project id

Example: "ererf-erf-erf-erf"
stripePublishableKeystring

Stripe publishable key for tenant. Used in case of stripe payment.

firebaseTenantIdstring

Firebase tenant ID for tenant. This id is needed, if you choose to setup Firebase for user authentification for your project.

infuraApiKeystring

Infura API key for tenant. Used in for client interaction with web3 provider.

polyScanApiKeystring

PolyScan API key for tenant. Used in for client interaction with PolyScan.

clientIpLocationobject or null

Geolocation information derived from the client IP address

Response
application/json
{
  "projectName": "My Project",
  "id": "ererf-erf-erf-erf",
  "stripePublishableKey": "string",
  "firebaseTenantId": "string",
  "infuraApiKey": "string",
  "polyScanApiKey": "string",
  "clientIpLocation": {
    "country_code": "string",
    "country_name": "string",
    "region_code": "string",
    "region_name": "string",
    "city_name": "string",
    "postal_code": "string",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "accuracy_radius": 5
  }
}

Get login token

Request

Generate a login token for the project

Security
projectKey
curl -i -X GET \
  https://docs.pers.ninja/_mock/swagger/tenants/login-token \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Login token generated successfully

Bodyapplication/json
string
Response
application/json
"string"

Create new API key

Request

ADMIN: Create a new API key for the tenant. Store this key securely - it cannot be retrieved again.

Security
tenantAdminJWT
Bodyapplication/jsonrequired
keyNamestringrequired

name of the key

curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/tenants/api-keys \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "keyName": "string"
  }'

Responses

API key created successfully

Bodyapplication/json
projectNamestringrequired

Name of the tenant.

acronymstringrequired

Acronym of the tenant.

idstringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

createdAtstring(date-time)required

Date when tenant was created.

projectDescriptionstring

Description of the tenant.

projectWebsitestring

Website of the tenant.

projectEmailstring

Email of the tenant.

projectImageUrlstring

Image URL of the tenant.

projectApiKeystringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

testnetProjectApiKeystringrequired

Testnet project API key for tenant. Used in case of testnet project.

stripeApiKeystring

Stripe API key for tenant. Used in case of stripe payment.

stripeWebhookSecretstring

Stripe webhook secret for tenant. Used in case of stripe payment.

loginTokenstring

This is an optional field for any extra login requirements for your users.

allowJWTForUnauthenticatedUsersbooleanrequired

This is an optional field for any extra login requirements for your users.

firebaseTenantIdstring
jwtstring

JWT token for tenant admin user. This token is used to authenticate tenant admin user. It is generated when tenant is created. Please store it securely, you will not be able to see this again. However, you can generate a new one if needed.

apiPrivateKeystring

API private key for tenant. This key is used to authenticate tenant when making API requests. It is generated on demand. Please store it securely, you will not be able to see this again. However, you can generate a new one if needed.

defaultWalletManagementTypestringrequired

Default wallet management type for tenant. This is used when creating a new wallet for the tenant. It can be either CUSTODIAL or NON_CUSTODIAL. CUSTODIAL means that the wallet is managed by the platform, while NON_CUSTODIAL means that the wallet is managed by the user.

Default "custodial"
Enum"custodial""non-custodial"
Response
application/json
{
  "projectName": "string",
  "acronym": "string",
  "id": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "projectDescription": "string",
  "projectWebsite": "string",
  "projectEmail": "string",
  "projectImageUrl": "string",
  "projectApiKey": "string",
  "testnetProjectApiKey": "string",
  "stripeApiKey": "string",
  "stripeWebhookSecret": "string",
  "loginToken": "string",
  "allowJWTForUnauthenticatedUsers": true,
  "firebaseTenantId": "string",
  "jwt": "string",
  "apiPrivateKey": "string",
  "defaultWalletManagementType": "custodial"
}

Create new JWT token

Request

ADMIN: Create a new JWT token for the tenant. Store this token securely - it cannot be retrieved again.

Security
tenantAdminJWT
Bodyapplication/jsonrequired
isTestnetbooleanrequired

wheter the key is for testnet or mainnet

curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/tenants/jwt-tokens \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "isTestnet": true
  }'

Responses

JWT token created successfully

Bodyapplication/json
projectNamestringrequired

Name of the tenant.

acronymstringrequired

Acronym of the tenant.

idstringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

createdAtstring(date-time)required

Date when tenant was created.

projectDescriptionstring

Description of the tenant.

projectWebsitestring

Website of the tenant.

projectEmailstring

Email of the tenant.

projectImageUrlstring

Image URL of the tenant.

projectApiKeystringrequired

Unique identifier for tenant. This id is used to identify tenant in the system for client requests.

testnetProjectApiKeystringrequired

Testnet project API key for tenant. Used in case of testnet project.

stripeApiKeystring

Stripe API key for tenant. Used in case of stripe payment.

stripeWebhookSecretstring

Stripe webhook secret for tenant. Used in case of stripe payment.

loginTokenstring

This is an optional field for any extra login requirements for your users.

allowJWTForUnauthenticatedUsersbooleanrequired

This is an optional field for any extra login requirements for your users.

firebaseTenantIdstring
jwtstring

JWT token for tenant admin user. This token is used to authenticate tenant admin user. It is generated when tenant is created. Please store it securely, you will not be able to see this again. However, you can generate a new one if needed.

apiPrivateKeystring

API private key for tenant. This key is used to authenticate tenant when making API requests. It is generated on demand. Please store it securely, you will not be able to see this again. However, you can generate a new one if needed.

defaultWalletManagementTypestringrequired

Default wallet management type for tenant. This is used when creating a new wallet for the tenant. It can be either CUSTODIAL or NON_CUSTODIAL. CUSTODIAL means that the wallet is managed by the platform, while NON_CUSTODIAL means that the wallet is managed by the user.

Default "custodial"
Enum"custodial""non-custodial"
Response
application/json
{
  "projectName": "string",
  "acronym": "string",
  "id": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "projectDescription": "string",
  "projectWebsite": "string",
  "projectEmail": "string",
  "projectImageUrl": "string",
  "projectApiKey": "string",
  "testnetProjectApiKey": "string",
  "stripeApiKey": "string",
  "stripeWebhookSecret": "string",
  "loginToken": "string",
  "allowJWTForUnauthenticatedUsers": true,
  "firebaseTenantId": "string",
  "jwt": "string",
  "apiPrivateKey": "string",
  "defaultWalletManagementType": "custodial"
}

Admins

Operations

Tokens

Operations

Campaigns

Operations

Campaign Tags

Operations

Campaign Tokens

Operations

Campaign Triggers

Operations

Campaign Engagements

Operations

Campaign Claims

Operations

Redemptions

Operations

Purchases

Operations

Businesses

Operations

Transactions

Operations

Users

Operations

Balances

Operations

Files

Operations

Web3 Chains

Operations

Contracts

Operations

Auth

Operations

Root

Operations

Well-known

Operations