Skip to content

PERS-api docs (2.0.5)

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 (Simplified)

Request

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

USER AUTHENTICATION:

  • Header: X-API-Key (tenant identification)
  • Body: { authToken: "jwt_from_provider", authType?: "user" }
  • Returns: User session with PERS JWT tokens

ADMIN AUTHENTICATION:

  • Header: X-API-Key (tenant identification)
  • Body: { authToken: "firebase_jwt", authType: "tenant" }
  • Returns: Admin session with PERS JWT tokens

All authentication now uses consistent API key + token-in-body pattern.

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"
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"
  }'

Responses

Token created successfully

Bodyapplication/json
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.

refreshTokenstringrequired

JWT refresh token this token is used to get a new access token when the current one expires. It is valid for 1 day.

Response
application/json
{
  "accessToken": "string",
  "refreshToken": "string"
}

Refresh authentication tokens

Request

Refresh access tokens using valid refresh token

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

refreshTokenstringrequired

JWT refresh token this token is used to get a new access token when the current one expires. It is valid for 1 day.

curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/auth/refresh \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-project-key: YOUR_API_KEY_HERE' \
  -d '{
    "accessToken": "string",
    "refreshToken": "string"
  }'

Responses

New access token created

Bodyapplication/json
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.

refreshTokenstringrequired

JWT refresh token this token is used to get a new access token when the current one expires. It is valid for 1 day.

Response
application/json
{
  "accessToken": "string",
  "refreshToken": "string"
}

Root

Operations

Well-known

Operations

Business Types

Operations

Redemption Redeems

Operations

Redemption Types

Operations

Redemption Tokens

Operations