persona-ci-integration View full skill →

CI/CD pipeline for Persona integrations with sandbox API testing.

ReadWriteEditBash(gh:*)

persona-common-errors View full skill →

Fix top Persona API errors: 401, 422, webhook signature failures, inquiry state issues.

ReadGrepBash(curl:*)

persona-core-workflow-a View full skill →

Build a complete KYC verification flow with Persona inquiries and embedded UI.

ReadWriteEditBash(npm:*)Grep

Persona Core Workflow A — KYC Inquiry Flow

Overview

Build a complete KYC onboarding flow: create an inquiry from a template, embed the Persona verification UI in your web app, handle completion callbacks, and store verification results.

Prerequisites

Completed persona-install-auth setup
Inquiry Template configured in Persona Dashboard
Web application with a frontend (React, HTML, etc.)

Instructions

Step 1: Backend — Create Inquiry Endpoint


// server.ts — Express endpoint to create inquiries
import express from 'express';
import axios from 'axios';

const app = express();
app.use(express.json());

const persona = axios.create({
  baseURL: 'https://withpersona.com/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.PERSONA_API_KEY}`,
    'Persona-Version': '2023-01-05',
  },
});

app.post('/api/verify', async (req, res) => {
  const { userId, email } = req.body;

  const { data } = await persona.post('/inquiries', {
    data: {
      attributes: {
        'inquiry-template-id': process.env.PERSONA_TEMPLATE_ID,
        'reference-id': userId,
        'fields': {
          'email-address': { type: 'string', value: email },
        },
      },
    },
  });

  res.json({
    inquiryId: data.data.id,
    sessionToken: data.data.attributes['session-token'],
  });
});

Step 2: Frontend — Embed Persona Flow


<!-- Include Persona's JavaScript SDK -->
<script src="https://cdn.withpersona.com/dist/persona-v5.0.0.js"></script>

<button id="verify-btn">Verify Identity</button>

<script>
document.getElementById('verify-btn').addEventListener('click', async () => {
  // Get inquiry from your backend
  const resp = await fetch('/api/verify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userId: 'user-123', email: 'alice@example.com' }),
  });
  const { inquiryId, sessionToken } = await resp.json();

  // Launch Persona embedded flow
  const client = new Persona.Client({
    inquiryId,
    sessionToken,
    onComplete: ({ inquiryId, status }) => {
      console.log(`Verification ${status} for inquiry ${inquiryId}`);
      // Notify your backend
      fetch(`/api/verify/${inquiryId}/complete`, { method: 'POST' });
    },
    onCancel: ({ inquiryId }) => {
      console.log('User cancelled verification');
    },
    onError: (error) => {
      console.error('Persona error:', error);
    },
  });

  client.open();
});
</script>

Step 3: Backend — Handle Completion


app.po…

persona-core-workflow-b View full skill →

Work with Persona verification types: government ID, selfie, database checks.

ReadWriteEditBash(curl:*)Grep

Persona Core Workflow B — Verification Checks

Overview

Work with Persona's verification types: government ID (passport, driver's license), selfie liveness detection, and database checks (SSN, watchlist). Covers retrieving verification details, interpreting check results, and handling edge cases.

Prerequisites

Completed persona-core-workflow-a (inquiry flow)
Inquiry Template with verification checks configured

Instructions

Step 1: List Verifications for an Inquiry


import os, requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": "2023-01-05",
}
BASE = "https://withpersona.com/api/v1"

# Get all verifications for an inquiry
resp = requests.get(f"{BASE}/inquiries/inq_XXXXX", headers=HEADERS)
resp.raise_for_status()
inquiry = resp.json()["data"]
verifications = inquiry["relationships"]["verifications"]["data"]

for v in verifications:
    v_resp = requests.get(f"{BASE}/verifications/{v['id']}", headers=HEADERS)
    v_data = v_resp.json()["data"]["attributes"]
    print(f"  Type: {v['type']}")
    print(f"  Status: {v_data['status']}")  # passed, failed, requires_retry
    print(f"  Checks: {v_data.get('checks', [])}")

Step 2: Government ID Verification Results


# Government ID verification includes extracted data
def get_gov_id_details(verification_id: str) -> dict:
    resp = requests.get(f"{BASE}/verifications/{verification_id}", headers=HEADERS)
    resp.raise_for_status()
    attrs = resp.json()["data"]["attributes"]

    return {
        "status": attrs["status"],
        "first_name": attrs.get("name-first"),
        "last_name": attrs.get("name-last"),
        "dob": attrs.get("birthdate"),
        "id_number": attrs.get("identification-number"),
        "id_class": attrs.get("id-class"),          # dl, pp, id
        "country": attrs.get("country-code"),
        "expiry": attrs.get("expiration-date"),
        "checks": {
            check["name"]: check["status"]
            for check in attrs.get("checks", [])
        },
    }

# Example checks: id_barcode_detection, id_integrity, id_selfie_comparison

Step 3: Selfie Liveness Check


def get_selfie_result(verification_id: str) -> dict:
    resp = requests.get(f"{BASE}/verifications/{verification_id}", headers=HEADERS)
    attrs = resp.json()["data…

persona-cost-tuning View full skill →

Optimize Persona verification costs with template selection and caching.

ReadGrep

persona-debug-bundle View full skill →

Collect Persona diagnostic info: inquiry IDs, API responses, webhook logs.

ReadBash(grep:*)Bash(curl:*)Bash(tar:*)Grep

persona-deploy-integration View full skill →

Deploy Persona verification service to cloud platforms.

ReadWriteEditBash(gcloud:*)

persona-hello-world View full skill →

Create your first Persona identity verification inquiry and check its status.

ReadWriteEditBash(curl:*)

Persona Hello World

Overview

Create a Persona inquiry, generate an embed URL for the verification flow, and poll for the inquiry status. Uses the real Persona REST API with sandbox credentials.

Prerequisites

Completed persona-install-auth setup
An Inquiry Template ID from the Persona Dashboard (format: itmpl_*)

Instructions

Step 1: Create an Inquiry


import os, requests

API_KEY = os.environ["PERSONA_API_KEY"]
BASE = "https://withpersona.com/api/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Persona-Version": "2023-01-05",
    "Content-Type": "application/json",
}

# Create a new inquiry from a template
resp = requests.post(f"{BASE}/inquiries", headers=HEADERS, json={
    "data": {
        "attributes": {
            "inquiry-template-id": "itmpl_YOUR_TEMPLATE_ID",
            "reference-id": "user-12345",  # Your internal user ID
        }
    }
})
resp.raise_for_status()
inquiry = resp.json()["data"]
inquiry_id = inquiry["id"]
status = inquiry["attributes"]["status"]
print(f"Inquiry created: {inquiry_id} (status: {status})")

Step 2: Get the Verification URL


# The inquiry includes a session token for the embedded flow
session_token = inquiry["attributes"].get("session-token")
if session_token:
    # Option A: Hosted flow (redirect user to Persona)
    hosted_url = f"https://withpersona.com/verify?inquiry-id={inquiry_id}&session-token={session_token}"
    print(f"Send user to: {hosted_url}")

    # Option B: Embedded flow (JavaScript SDK in your page)
    print(f"Embed with: Persona.Client({{ templateId: 'itmpl_...', inquiryId: '{inquiry_id}' }})")

Step 3: Poll for Completion


import time

for _ in range(30):  # Poll for up to 5 minutes
    resp = requests.get(f"{BASE}/inquiries/{inquiry_id}", headers=HEADERS)
    resp.raise_for_status()
    status = resp.json()["data"]["attributes"]["status"]
    print(f"  Status: {status}")

    if status in ("completed", "approved", "declined"):
        break
    time.sleep(10)

# Get verification details
if status == "completed":
    verifications = resp.json()["data"]["relationships"]["verifications"]["data"]
    for v in verifications:
        print(f"  Verification: {v['type']} — {v['id']}")

Step 4: Retrieve Verification Results


# Get detailed verification result
ver…

persona-install-auth View full skill →

Configure Persona API authentication with sandbox and production API keys.

ReadWriteEditBash(npm:*)Bash(pip:*)Grep

Persona Install & Auth

Overview

Set up Persona API authentication. Persona uses Bearer token auth with environment-prefixed API keys (persona_sandbox_* for testing, persona_production_* for live). No SDK required -- direct REST API calls with any HTTP client.

Prerequisites

Persona account at withpersona.com
At least one Inquiry Template configured in the Persona Dashboard
Node.js 18+ or Python 3.9+

Instructions

Step 1: Get API Keys


1. Log into dashboard.withpersona.com
2. Go to Settings > API Keys
3. Copy your sandbox key (starts with persona_sandbox_)
4. For production: copy production key (starts with persona_production_)

Step 2: Configure Environment


# .env — never commit
PERSONA_API_KEY=persona_sandbox_xxxxxxxxxxxxxxxxxxxxxxxx
PERSONA_API_VERSION=2023-01-05

# .gitignore
echo '.env' >> .gitignore

Step 3: Install HTTP Client


set -euo pipefail
# Node.js
npm install axios dotenv

# Python
pip install requests python-dotenv

Step 4: Verify Connection (Node.js)


import axios from 'axios';

const persona = axios.create({
  baseURL: 'https://withpersona.com/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.PERSONA_API_KEY}`,
    'Persona-Version': process.env.PERSONA_API_VERSION || '2023-01-05',
    'Content-Type': 'application/json',
  },
});

async function verify() {
  const { data } = await persona.get('/inquiries?page[size]=1');
  console.log(`Connected! Found ${data.data.length} inquiry(ies).`);
}
verify().catch(console.error);

Step 5: Verify Connection (Python)


import os, requests
from dotenv import load_dotenv

load_dotenv()

headers = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": os.environ.get("PERSONA_API_VERSION", "2023-01-05"),
}

resp = requests.get("https://withpersona.com/api/v1/inquiries?page[size]=1", headers=headers)
resp.raise_for_status()
print(f"Connected! Status: {resp.status_code}")

Output

API key configured and verified
HTTP client set up with correct headers
Successful test call to Persona API

Error Handling

…

Error	Cause	Solution
`401 Unauthorized`	Invalid or expired API key	Verify key in Dashboard > Settings > API Keys
`403 Forbidden`	Key doesn't match environment

persona-local-dev-loop View full skill →

Local development with Persona sandbox, ngrok for webhooks, mock verifications.

ReadWriteEditBash(npm:*)Grep

persona local dev loop | sed 's/\b\(.\)/\u\1/g'

Overview

Sandbox testing with test inquiry templates, ngrok tunnel for webhook testing, mock API responses for CI.

Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions

Step 1: Set Up Sandbox Environment


set -euo pipefail
# Use sandbox API key for all development
echo 'PERSONA_API_KEY=persona_sandbox_xxxxxxxx' > .env
echo 'PERSONA_API_VERSION=2023-01-05' >> .env

Step 2: Expose Local Webhooks with ngrok


# Terminal 1: Start your webhook server
npm run dev  # localhost:3000

# Terminal 2: Tunnel with ngrok
ngrok http 3000
# Copy the HTTPS URL and configure in Persona Dashboard > Webhooks

Step 3: Create Test Inquiries


import os, requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": "2023-01-05",
}

# Create inquiry with sandbox template
resp = requests.post("https://withpersona.com/api/v1/inquiries", headers=HEADERS, json={
    "data": {
        "attributes": {
            "inquiry-template-id": "itmpl_YOUR_SANDBOX_TEMPLATE",
            "reference-id": f"test-{int(time.time())}",
        }
    }
})
print(f"Test inquiry: {resp.json()['data']['id']}")

Step 4: Mock API Responses for CI


import { vi } from 'vitest';

const mockPersonaApi = {
  createInquiry: vi.fn().mockResolvedValue({
    data: { id: 'inq_test_123', attributes: { status: 'created', 'session-token': 'tok_xxx' } },
  }),
  getInquiry: vi.fn().mockResolvedValue({
    data: { id: 'inq_test_123', attributes: { status: 'completed' } },
  }),
};

Output

Sandbox environment configured for development
ngrok tunnel for webhook testing
Test inquiry creation workflow
Mock API responses for unit tests

Error Handling

Error	Cause	Solution
Webhook not received	ngrok URL not configured	Update webhook URL in Dashboard
Sandbox key rejected	Using production key	Verify key starts with `persona_sandbox_`
Template not found	Wrong environment	Templates are per-environment

Resources

persona-performance-tuning View full skill →

Optimize Persona API performance with batching and caching.

ReadWriteEdit

persona-prod-checklist View full skill →

Production deployment checklist for Persona identity verification.

ReadBash(curl:*)Grep

persona-rate-limits View full skill →

Handle Persona API rate limits with exponential backoff and request queuing.

ReadWriteEdit

persona-reference-architecture View full skill →

KYC service architecture with Persona as verification provider.

ReadGrep

persona-sdk-patterns View full skill →

Production Persona API client wrapper with retry, pagination, typed responses.

ReadWriteEdit

persona sdk patterns | sed 's/\b\(.\)/\u\1/g'

Overview

Singleton API client, typed verification results, pagination through inquiries, error classification.

Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions

Step 1: Typed API Client Wrapper


import axios, { AxiosInstance, AxiosError } from 'axios';

interface PersonaConfig {
  apiKey: string;
  version?: string;
  baseURL?: string;
}

class PersonaClient {
  private http: AxiosInstance;

  constructor(config: PersonaConfig) {
    this.http = axios.create({
      baseURL: config.baseURL || 'https://withpersona.com/api/v1',
      headers: {
        'Authorization': `Bearer ${config.apiKey}`,
        'Persona-Version': config.version || '2023-01-05',
        'Content-Type': 'application/json',
      },
    });
  }

  async createInquiry(templateId: string, referenceId: string, fields?: Record<string, any>) {
    const { data } = await this.http.post('/inquiries', {
      data: { attributes: { 'inquiry-template-id': templateId, 'reference-id': referenceId, fields } },
    });
    return data.data;
  }

  async getInquiry(inquiryId: string) {
    const { data } = await this.http.get(`/inquiries/${inquiryId}`);
    return data.data;
  }

  async listInquiries(params: { referenceId?: string; status?: string; pageSize?: number } = {}) {
    const { data } = await this.http.get('/inquiries', {
      params: {
        'filter[reference-id]': params.referenceId,
        'filter[status]': params.status,
        'page[size]': params.pageSize || 25,
      },
    });
    return data.data;
  }

  async getVerification(verificationId: string) {
    const { data } = await this.http.get(`/verifications/${verificationId}`);
    return data.data;
  }
}

// Singleton
let _client: PersonaClient | null = null;
export function getPersonaClient(): PersonaClient {
  if (!_client) {
    _client = new PersonaClient({ apiKey: process.env.PERSONA_API_KEY! });
  }
  return _client;
}

Step 2: Error Classification


function classifyPersonaError(error: AxiosError): { retryable: boolean; message: string } {
  const status = error.response?.status;
  if (status === 429) return { retryable: true, message: 'Rate limited' };
  if (status && status >= 500) return { retryable: true, message: 'Server error' };
  if (status === 401) return { retryable: false, message: 'Invalid API key' };
  if (status === 422) return { retryable: false, message: 'Invalid request' };
  return { retryable: false, message: error.message };
}

Output

Typed Persona API client with inquiry and verification methods

persona-security-basics View full skill →

Secure Persona API keys, webhook secrets, PII handling in verification data.

ReadWriteGrep

persona-upgrade-migration View full skill →

Upgrade Persona API versions and handle breaking changes.

ReadWriteEditBash(npm:*)Bash(git:*)

persona-webhooks-events View full skill →

Handle Persona webhook events for inquiry and verification status changes.

ReadWriteEditBash(curl:*)

persona webhooks events | sed 's/\b\(.\)/\u\1/g'

Overview

HMAC signature verification, inquiry.completed/approved/declined events, idempotent processing.

Prerequisites

Completed persona-install-auth setup
Valid Persona API key (sandbox or production)

Instructions

Step 1: Configure Webhook in Dashboard


1. Dashboard > Settings > Webhooks > Add Webhook
2. URL: https://your-app.com/webhooks/persona
3. Events: inquiry.completed, inquiry.approved, inquiry.declined,
           verification.passed, verification.failed
4. Copy the webhook secret for signature verification

Step 2: Webhook Endpoint with HMAC Verification


import express from 'express';
import crypto from 'crypto';

const app = express();

app.post('/webhooks/persona',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['persona-signature'] as string;
    const secret = process.env.PERSONA_WEBHOOK_SECRET!;

    // Verify HMAC-SHA256 signature
    const expectedSig = crypto
      .createHmac('sha256', secret)
      .update(req.body)
      .digest('hex');

    if (!crypto.timingSafeEqual(Buffer.from(signature || ''), Buffer.from(expectedSig))) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const event = JSON.parse(req.body.toString());
    await handlePersonaEvent(event);
    res.status(200).json({ received: true });
  }
);

Step 3: Event Handlers


async function handlePersonaEvent(event: any) {
  const { type, data } = event;

  switch (type) {
    case 'inquiry.completed':
      const inquiryId = data.attributes.payload.data.id;
      const referenceId = data.attributes.payload.data.attributes['reference-id'];
      console.log(`Inquiry completed: ${inquiryId} for user ${referenceId}`);
      // Update user KYC status in your database
      await updateUserKycStatus(referenceId, 'completed');
      break;

    case 'inquiry.approved':
      await updateUserKycStatus(data.attributes.payload.data.attributes['reference-id'], 'approved');
      break;

    case 'inquiry.declined':
      await updateUserKycStatus(data.attributes.payload.data.attributes['reference-id'], 'declined');
      break;

    case 'verification.passed':
      console.log(`Verification passed: ${data.attributes.payload.data.id}`);
      break;

    case 'verification.failed':
      console.log(`Verification failed: ${data.attributes.payload.data.id}`);
      break;

    default:
      console.log(`Unhandled event: ${type}`);
  }
}

Step 4: Idempotent Processing


co…

Error	Cause	Solution
401 Unauthorized	Invalid API key	Check PERSONA_API_KEY
429 Rate Limited	Too many requests	Implement backoff
404 Not Found	Wrong resource ID	Verify ID format

HTTP Code	Meaning	Retryable
400	Bad request	No
401	Invalid API key	No — fix key
404	Resource not found	No
409	Conflict (terminal state)	No
422	Validation error	No — fix request
429	Rate limited	Yes

Error	Cause	Solution
401 Unauthorized	Invalid API key	Check PERSONA_API_KEY
429 Rate Limited	Too many requests	Implement backoff
404 Not Found	Wrong resource ID	Verify ID format

Error	Cause	Solution
401 Unauthorized	Invalid API key	Check PERSONA_API_KEY
429 Rate Limited	Too many requests	Implement backoff
404 Not Found	Wrong resource ID	Verify ID format

Error	Cause	Solution
401 Unauthorized	Invalid API key	Check PERSONA_API_KEY
429 Rate Limited	Too many requests	Implement backoff
404 Not Found	Wrong resource ID	Verify ID format

persona-pack

Installation

What It Does

Skills (18) plugin-local skills

persona ci integration | sed 's/\b\(.\)/\u\1/g'

Overview

Prerequisites

Instructions

Step 1: Implementation

Output

Error Handling

Resources

Next Steps

persona common errors | sed 's/\b\(.\)/\u\1/g'

Overview

Prerequisites

Instructions

Error 1: 401 Unauthorized

Error 2: 422 Invalid Inquiry Template

Error 3: Webhook Signature Mismatch

Error 4: 429 Rate Limited

Error 5: Inquiry Already Completed

Error 6: 404 Inquiry Not Found

Output

Error Handling

Persona Core Workflow A — KYC Inquiry Flow

Overview

Prerequisites

Instructions

Step 1: Backend — Create Inquiry Endpoint

Step 2: Frontend — Embed Persona Flow

Step 3: Backend — Handle Completion

Persona Core Workflow B — Verification Checks

Overview

Prerequisites

Instructions

Step 1: List Verifications for an Inquiry

Step 2: Government ID Verification Results

Step 3: Selfie Liveness Check

persona cost tuning | sed 's/\b\(.\)/\u\1/g'

Overview

Prerequisites

Instructions

Step 1: Implementation

Output

Error Handling

Resources

Next Steps

persona debug bundle | sed 's/\b\(.\)/\u\1/g'

Overview

Prerequisites

Instructions

Step 1: Implementation

Output

Error Handling

Resources

Next Steps

persona deploy integration | sed 's/\b\(.\)/\u\1/g'

Overview

Prerequisites

Instructions

Step 1: Implementation

Output

Error Handling

Resources

Next Steps

Persona Hello World

Overview

Prerequisites

Instructions

Step 1: Create an Inquiry

Step 2: Get the Verification URL

Step 3: Poll for Completion

Step 4: Retrieve Verification Results

Persona Install & Auth

Overview

Prerequisites

Instructions

Step 1: Get API Keys

Step 2: Configure Environment