Skip to content
/
Authentication & Authoriz...

PERS-api Documentation (2.0.13)

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

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

Request

Universal token creation with consistent token-in-body pattern.

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
Security
projectKey
Bodyapplication/jsonrequired

Authentication request with token and type. authType defaults to "user" if not specified.

authTokenstringrequired

Authentication token from WebAuthn provider (e.g., PERS Signer API)

Example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJFZERTQSJ9..."
authTypestring

Authentication context type - explicitly declares intent for admin vs user auth

Enum"user""business""tenant""system""external"
contextobject

Optional context for explicit business/tenant selection. Required when user has multiple memberships of that type.

rawLoginDataobject

if Tenant settings allowJWTForUnauthenticatedUsers is true, this field contains data to create user and setup unauthenticated user session instead of token verification. Useful for sandbox or trial modes. For now it is only used to create unauthenticated users.

Example: {"someKey":"someValue"}
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/auth/token \
  -H 'Content-Type: application/json' \
  -H 'x-project-key: YOUR_API_KEY_HERE' \
  -d '{
    "authToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFZERTQSJ9...",
    "authType": "user",
    "context": {
      "businessId": "550e8400-e29b-41d4-a716-446655440000",
      "tenantId": "550e8400-e29b-41d4-a716-446655440001"
    },
    "rawLoginData": {
      "someKey": "someValue"
    }
  }'

Responses

Token created successfully

Bodyapplication/json
refreshTokenstringrequired

refresh token

Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRJZCI6IjEiLCJpYXQiOjE2MjYxNzUwNzksImV4cCI6MTYyNjE3NTI3OX0.5w8A6t7b5lBx8D3FmLwJQgJ9z1D9c9Vz7A3f7BvzH2A"
accessTokenstringrequired

JWT access token this token is used to authenticate the user, by default it expires in 15 minutes, and it should be sent in the Authorization header as Bearer token.

Response
application/json
{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRJZCI6IjEiLCJpYXQiOjE2MjYxNzUwNzksImV4cCI6MTYyNjE3NTI3OX0.5w8A6t7b5lBx8D3FmLwJQgJ9z1D9c9Vz7A3f7BvzH2A",
  "accessToken": "string"
}

Refresh authentication tokens

Request

Refresh access tokens using valid refresh token

Security
projectKey
Bodyapplication/jsonrequired

Refresh token request

refreshTokenstringrequired

refresh token

Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRJZCI6IjEiLCJpYXQiOjE2MjYxNzUwNzksImV4cCI6MTYyNjE3NTI3OX0.5w8A6t7b5lBx8D3FmLwJQgJ9z1D9c9Vz7A3f7BvzH2A"
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/auth/refresh \
  -H 'Content-Type: application/json' \
  -H 'x-project-key: YOUR_API_KEY_HERE' \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRJZCI6IjEiLCJpYXQiOjE2MjYxNzUwNzksImV4cCI6MTYyNjE3NTI3OX0.5w8A6t7b5lBx8D3FmLwJQgJ9z1D9c9Vz7A3f7BvzH2A"
  }'

Responses

New access token created

Bodyapplication/json
refreshTokenstringrequired

refresh token

Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRJZCI6IjEiLCJpYXQiOjE2MjYxNzUwNzksImV4cCI6MTYyNjE3NTI3OX0.5w8A6t7b5lBx8D3FmLwJQgJ9z1D9c9Vz7A3f7BvzH2A"
accessTokenstringrequired

JWT access token this token is used to authenticate the user, by default it expires in 15 minutes, and it should be sent in the Authorization header as Bearer token.

Response
application/json
{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRJZCI6IjEiLCJpYXQiOjE2MjYxNzUwNzksImV4cCI6MTYyNjE3NTI3OX0.5w8A6t7b5lBx8D3FmLwJQgJ9z1D9c9Vz7A3f7BvzH2A",
  "accessToken": "string"
}

Verify JWT token

Request

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

Security
projectKey
Bodyapplication/jsonrequired

Token verification request

authTokenstringrequired

JWT token to verify (any issuer)

Example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/auth/verify \
  -H 'Content-Type: application/json' \
  -H 'x-project-key: YOUR_API_KEY_HERE' \
  -d '{
    "authToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Responses

Token verification completed (check valid field for result)

Bodyapplication/json
validbooleanrequired

Whether the token verification was successful

Example: true
payloadobject

Decoded payload from the token if verification is successful

Example: null
tenantIdobjectrequired

Error message if token verification fails

Example: "Invalid token"
identifierEmailobject

Universal identifier email for the authenticated entity

Example: "user-c8e619a4f7f8419d94320d403213ef49@id.pers.ninja"
errorMessagestring

Error message if token verification fails

Example: "Invalid token"
Response
application/json
{
  "valid": true,
  "payload": null,
  "tenantId": "Invalid token",
  "identifierEmail": "user-c8e619a4f7f8419d94320d403213ef49@id.pers.ninja",
  "errorMessage": "Invalid token"
}

Root

Operations

Well-known

Operations

Trigger Sources

Operations

Business Types

Operations

Redemption Types

Operations

Redemption Redeems

Operations

Redemption Tokens

Operations

API Keys

Operations