Skip to content
/
Verify JWT token

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

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"
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",
    "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 and businessApiKey
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-api-key: YOUR_API_KEY_HERE' \
  -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 and businessApiKey
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-api-key: YOUR_API_KEY_HERE' \
  -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
errorMessagestring

Error message if token verification fails

Example: "Invalid token"
Response
application/json
{
  "valid": true,
  "payload": null,
  "errorMessage": "Invalid token"
}

Root

Operations

Well-known

Operations

webhooks

Business Types

Operations

Redemption Types

Operations

Redemption Redeems

Operations

Redemption Tokens

Operations

API Keys

Operations