Skip to content

PERS-api Documentation (2.2.2)

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.

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

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

Trigger Sources

Operations

Business Types

Operations

Redemption Types

Operations

Redemption Redeems

Operations

Redemption Tokens

Operations

API Keys

Operations

Get all tenant API keys (Admin)

Request

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).

Security
authJWT
Query
typestring

Optional filter by integration API key type (database-stored tokens that can be revoked)

Value"TENANT_SYSTEM_JWT"
includeRevokedboolean

Include revoked API keys in results (default: false)

pagenumber

Page number for pagination (1-based)

limitnumber

Items per page for pagination

curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/api-keys?type=TENANT_SYSTEM_JWT&includeRevoked=true&page=0&limit=0' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successfully retrieved tenant API keys

Bodyapplication/jsonArray [
idstringrequired

Unique identifier for the API key

Example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
typestringrequired

Type of API key

Enum"TENANT_SYSTEM_JWT""ADMIN_JWT_ACCESS_TOKEN""ADMIN_JWT_REFRESH_TOKEN""USER_JWT_ACCESS_TOKEN""USER_JWT_REFRESH_TOKEN""BUSINESS_JWT_ACCESS_TOKEN""BUSINESS_JWT_REFRESH_TOKEN""BLOCKCHAIN_WRITER_JWT""BLOCKCHAIN_READER_JWT""TRANSACTION_JWT_ACCESS_TOKEN"
Example: "TENANT_SYSTEM_JWT"
nameobject or null

Human-readable name for the API key

Example: "JWT Token (Mainnet) - 2025-11-22"
createdAtstring(date-time)required

Creation timestamp

Example: "2025-11-22T10:30:00.000Z"
shortenedPrivateKeystring<= 20 charactersrequired

Token preview for dashboard identification (first 8 + last 4 characters)

Example: "eyJhbGci...xMjM"
expiresAtobject or null

Expiration timestamp (null = no expiry)

Example: "2026-11-22T10:30:00.000Z"
isRevokedbooleanrequired

Indicates if the API key has been revoked

Example: false
lastUsedAtobject or null

Last time the API key was used for authentication

Example: "2025-11-24T14:30:00.000Z"
]
Response
application/json
[
  {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type": "TENANT_SYSTEM_JWT",
    "name": "JWT Token (Mainnet) - 2025-11-22",
    "createdAt": "2025-11-22T10:30:00.000Z",
    "shortenedPrivateKey": "eyJhbGci...xMjM",
    "expiresAt": "2026-11-22T10:30:00.000Z",
    "isRevoked": false,
    "lastUsedAt": "2025-11-24T14:30:00.000Z"
  }
]

Create new JWT token (Admin)

Request

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.

Security
authJWT
Bodyapplication/jsonrequired
namestringrequired

name of the key

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

Responses

JWT token created successfully

Bodyapplication/json
idstringrequired

Unique identifier for the API key

Example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
typestringrequired

Type of API key

Enum"TENANT_SYSTEM_JWT""ADMIN_JWT_ACCESS_TOKEN""ADMIN_JWT_REFRESH_TOKEN""USER_JWT_ACCESS_TOKEN""USER_JWT_REFRESH_TOKEN""BUSINESS_JWT_ACCESS_TOKEN""BUSINESS_JWT_REFRESH_TOKEN""BLOCKCHAIN_WRITER_JWT""BLOCKCHAIN_READER_JWT""TRANSACTION_JWT_ACCESS_TOKEN"
Example: "TENANT_SYSTEM_JWT"
nameobject or null

Human-readable name for the API key

Example: "JWT Token (Mainnet) - 2025-11-22"
createdAtstring(date-time)required

Creation timestamp

Example: "2025-11-22T10:30:00.000Z"
shortenedPrivateKeystring<= 20 charactersrequired

Token preview for dashboard identification (first 8 + last 4 characters)

Example: "eyJhbGci...xMjM"
expiresAtobject or null

Expiration timestamp (null = no expiry)

Example: "2026-11-22T10:30:00.000Z"
isRevokedbooleanrequired

Indicates if the API key has been revoked

Example: false
lastUsedAtobject or null

Last time the API key was used for authentication

Example: "2025-11-24T14:30:00.000Z"
privateKeystringrequired

Full private key/token - STORE SECURELY! Only returned once during creation

Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
Response
application/json
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "TENANT_SYSTEM_JWT",
  "name": "JWT Token (Mainnet) - 2025-11-22",
  "createdAt": "2025-11-22T10:30:00.000Z",
  "shortenedPrivateKey": "eyJhbGci...xMjM",
  "expiresAt": "2026-11-22T10:30:00.000Z",
  "isRevoked": false,
  "lastUsedAt": "2025-11-24T14:30:00.000Z",
  "privateKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Revoke API key (Admin)

Request

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.

Security
authJWT
Path
idstringrequired

Unique identifier of the API key to revoke

Example: f47ac10b-58cc-4372-a567-0e02b2c3d479
curl -i -X DELETE \
  https://docs.pers.ninja/_mock/swagger/api-keys/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

API key successfully revoked

Bodyapplication/json
validbooleanrequired

Whether the API key verification was successful

Example: true
payloadobject

JWT payload data if verification was successful

apiKeyobject

API key metadata if verification was successful

tenantIdobjectrequired

Tenant ID associated with the API key

Example: "tenant_12345"
Response
application/json
{
  "valid": true,
  "payload": {},
  "apiKey": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type": "TENANT_SYSTEM_JWT",
    "name": "JWT Token (Mainnet) - 2025-11-22",
    "createdAt": "2025-11-22T10:30:00.000Z",
    "shortenedPrivateKey": "eyJhbGci...xMjM",
    "expiresAt": "2026-11-22T10:30:00.000Z",
    "isRevoked": false,
    "lastUsedAt": "2025-11-24T14:30:00.000Z"
  },
  "tenantId": "tenant_12345"
}