Skip to content

PERS-api docs (2.0.7)

Download OpenAPI description
swagger.json
swagger.yaml
Overview
Languages
Servers
Mock server
https://docs.pers.ninja/_mock/swagger/
https://explorins-loyalty.ngrok.io/
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

webhooks

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.

Security
tenantAdminJWT
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)

curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/api-keys?type=TENANT_SYSTEM_JWT&includeRevoked=true' \
  -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""BLOCKCHAIN_WRITER_JWT""BLOCKCHAIN_READER_JWT""TENANT_ADMIN_JWT"
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
tenantAdminJWT
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""BLOCKCHAIN_WRITER_JWT""BLOCKCHAIN_READER_JWT""TENANT_ADMIN_JWT"
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
tenantAdminJWT
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
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"
  }
}